# The-Snip REST API — give this file to your AI assistant

Paste this file into your assistant's context — CLAUDE.md, project instructions, or
a system prompt — so it can read and write your team's The-Snip base over plain
HTTP. If your assistant's harness speaks MCP, prefer the hosted MCP server — the
same eight operations with zero glue: https://the-snip.com/docs/mcp

## What this connects you 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. Search it
before solving a problem the team may have solved already, and file new knowledge
back so the base stays current.

## Base URL and auth

    https://the-snip.com/api/v1

Send a workspace API key as a Bearer token on every request:

    Authorization: Bearer snip_YOUR_KEY

Keys are workspace-scoped and hashed at rest; every request reads and writes only
the key's workspace.

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

1. Create a workspace at https://the-snip.com — free, no card.
2. Open Settings → API keys in the app and generate a key. It starts with snip_
   and is shown exactly 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. Store it where your scripts can read it — an environment variable such as
   THESNIP_API_KEY. Never commit the key.

## The eight operations (this is the whole API)

There are no delete endpoints on the v1 surface: these eight operations are
the whole API.

### Search — POST /api/v1/search (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.

    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"}'

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

### Get an item — GET /api/v1/items/{id}

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

    curl https://the-snip.com/api/v1/items/ITEM_ID \
      -H "Authorization: Bearer snip_YOUR_KEY"

### List collections — GET /api/v1/collections

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

    curl https://the-snip.com/api/v1/collections \
      -H "Authorization: Bearer snip_YOUR_KEY"

### Create a snippet — POST /api/v1/snippets

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.

    curl -X POST https://the-snip.com/api/v1/snippets \
      -H "Authorization: Bearer snip_YOUR_KEY" -H "Content-Type: application/json" \
      -d '{"title":"Debounce","language":"typescript","code":"export const debounce = ..."}'

    { "title": string, "language": string, "code": string,
      "description"?: string, "collectionId"?: string, "sampleOutput"?: string,
      "tags"?: string[] (up to 10) }

### Create an API entry — POST /api/v1/apis

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 a doc — POST /api/v1/docs

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 an item — PATCH /api/v1/items/{id}

Use when a search result is outdated or incomplete. Take ids from search results —
never guess them.

    { ...any create fields except tags, all optional }

### Create a collection — POST /api/v1/collections

Use when no existing collection fits — check GET /api/v1/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 201 with the new
collection including its id, ready to use as collectionId.

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

To file items into collections: list the collections, pass collectionId on a
create; an update 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.
(Creating a collection is the exception: collections do not enter review.)

## Rate limits and error handling

Requests are limited to 60/min per workspace. Errors return
{ "error": { "code", "message" } }.

- 400 — invalid request. The schemas are strict; unknown fields are rejected.
- 401 — missing or invalid key. Send Authorization: Bearer snip_... and ask the
  human to check the key 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 a get or update — the id is not visible in your workspace. Search again
  and use an id from the results.
- 429 — rate limited. Back off and honor the Retry-After header.

## The CLI (optional, for humans and shell scripts)

The same API wraps into a zero-dependency CLI:

    curl -fsSL https://the-snip.com/cli -o ~/.local/bin/the-snip && chmod +x ~/.local/bin/the-snip
    the-snip login snip_YOUR_KEY
    the-snip search "retry with backoff"

Full reference: https://the-snip.com/docs/api