# The-Snip — instructions for AI agents

You have access to a team knowledge base called The-Snip. Paste this file into your
CLAUDE.md, project instructions, or system prompt so every agent session knows how to
read from and write to the team's base.

## What you have access to

The-Snip (https://the-snip.com) is a searchable, human-reviewed team knowledge base of
code snippets, saved API calls and Markdown docs. Approved items are trusted canon — a
human reviewed each one before it became part of the base. Treat search results as the
team's established answers, and file new knowledge back so the base stays current.

## Setup (one-time, a human does this)

1. Create a workspace at https://the-snip.com — free, no card.
2. In the app, open Settings → API keys and generate a workspace API key. It starts
   with snip_ and is shown once.
   Reads are free — any agent can search the base on the Free plan. Agent writes (create and update) need Pro & Team, $8/user/mo.
3. Export the key as an environment variable (for example THESNIP_API_KEY) or place
   it in your client's MCP config as shown below. Keys are workspace-scoped and hashed
   at rest; every query is tenant-isolated to the key's workspace.

## Connect over MCP

The hosted MCP endpoint is https://the-snip.com/mcp — Streamable HTTP (MCP spec
2025-03-26+), POST-only. Authenticate with the workspace key in the Authorization
header. Generic client config (Claude Code .mcp.json / Cursor .cursor/mcp.json):

    {
      "mcpServers": {
        "the-snip": {
          "url": "https://the-snip.com/mcp",
          "headers": { "Authorization": "Bearer snip_YOUR_KEY" }
        }
      }
    }

## Connect over REST (fallback)

If your harness cannot speak MCP, the same eight operations exist over REST.
Base URL: https://the-snip.com/api/v1 — same key, same Authorization header.

Search:

    curl -X POST https://the-snip.com/api/v1/search \
      -H "Authorization: Bearer snip_YOUR_KEY" -H "Content-Type: application/json" \
      -d '{"query":"retry with backoff","type":"snippet"}'

Get: GET /api/v1/items/{id}. Create: POST /api/v1/snippets | /api/v1/apis |
/api/v1/docs (same input schemas as the tools below). Update: PATCH
/api/v1/items/{id}. Collections: GET /api/v1/collections | POST /api/v1/collections.
All item writes land in review.

## The eight tools — and when to use them

### search_base — search the base (use this first, and often)

ALWAYS search the base before solving a problem the team may have solved already.
An empty query returns the most recent items. Results are scoped to your key's
workspace.

    { "query"?: string, "type"?: "snippet"|"api"|"doc", "language"?: string,
      "collectionId"?: string, "tags"?: string[],
      "sort"?: "relevance"|"updated"|"created"|"title", "limit"?: integer }

### get_item — fetch one item in full by id

Use when you have an id from search_base results and need the full item. Never
guess ids — an id outside your workspace returns 404. Free on every plan.

    { "id": string }

### list_collections — list the workspace's collections

Returns id and name rows. Check before filing: pass a real collectionId to
create_* or update_item so items land where the team expects them — never guess
collection ids. Free on every plan.

    {}

### create_snippet — file reusable code

Use when you wrote or fixed a piece of reusable code worth keeping: a hook, a helper,
a config block, a fix the team will hit again.

    { "title": string, "language": string, "code": string,
      "description"?: string, "collectionId"?: string, "sampleOutput"?: string }

### create_api — file a working API call

Use when you have a working API request worth saving — the method, URL, headers and
body that actually worked.

    { "title": string, "method": string, "url": string, "description"?: string,
      "collectionId"?: string, "headers"?: object, "requestBody"?: string,
      "sampleResponse"?: string }

### create_doc — file how-to or architecture knowledge

Use for knowledge that is prose rather than code: runbooks, how-tos, architecture
notes. The body is Markdown; [[wikilinks]] to other docs in the workspace are
supported.

    { "title": string, "body": string, "description"?: string, "collectionId"?: string }

### update_item — correct or extend an existing item

Use when a search result is outdated or incomplete. Patch by id — take ids from
search_base results, never guess them.

    { "id": string, ...any create fields, all optional }

### create_collection — create a collection to organize items

Use when no existing collection fits — check list_collections first and do not
create near-duplicates. Collections are organizational metadata: they do not enter
review and do not count against the item cap. Returns the new collection including
its id, ready to use as collectionId.

    { "name": string, "description"?: string }

To file items into collections: call list_collections, pass collectionId to
create_snippet / create_api / create_doc; update_item with collectionId moves an
existing item.

## The review contract (IMPORTANT)

Every item write you make — create or update — lands with status "in review". A human
approves it before it becomes canon. You CANNOT set the status yourself: the input
schemas reject unknown fields, so a smuggled status field comes back as a 400. Do not
re-submit an item because it is still in review — that is expected, not an error.
(create_collection is the exception: collections do not enter review.)

## Error handling

- 401 — missing or invalid key. Send the key as Authorization: Bearer snip_... and
  ask the human to check it in Settings → API keys (revoked or mistyped keys 401).
- 403 on a write — the message is: Agent writes need the Pro & Team plan — reads are free. Upgrade at https://the-snip.com/upgrade
  Reads never need the paid plan; ask the human to upgrade to enable writes. (On
  Free, the 25-item cap can also 403.)
- 404 on get_item or update_item — the id is not visible in your workspace. Search
  again with search_base and use an id from the results; never guess ids.
- 405 on GET /mcp — the endpoint is POST-only (Streamable HTTP). Configure your
  client for the Streamable HTTP transport, not SSE.
- 429 — rate limited. Back off and retry after the indicated delay.