Get a key, store a document, search it, and read it back. Every command here works verbatim once you fill in your key.

1. Get an API key

Sign in at https://ui.tupshar.housecarl.cloud, open the dashboard, and create a key. The tupk_… value is shown once — copy it before closing the dialog.

See API keys for details.

2. Set your environment

export TUPSHAR_HOST="https://api.tupshar.housecarl.cloud"
export TUPSHAR_KEY="tupk_…"   # paste your key here

3. Store a document

curl -sS -X POST "$TUPSHAR_HOST/v1/file" \
  -H "Authorization: Bearer $TUPSHAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "hello.md",
    "contents": "Tupshar is a document store with BM25 full-text search and an MCP twin.",
    "tags": ["demo"]
  }'

201 Created — save the id field from the response:

{
  "id": "01JZ8K3M9QF2YV7X4B6N0CWE5T",
  "filename": "hello.md",
  "tags": ["demo"],
  "version": 1,
  "etag": "\"sha256:3a7f…|1|1789…\"",
  "contents": "Tupshar is a document store with BM25 full-text search and an MCP twin."
}

The id is a server-assigned ULID. It addresses the document for every subsequent call — the filename is searchable metadata, not the address.

4. Search for it

curl -sS -G "$TUPSHAR_HOST/v1/query" \
  -H "Authorization: Bearer $TUPSHAR_KEY" \
  --data-urlencode "token=full-text search"

{
  "mode": "token",
  "results": [
    {
      "id": "01JZ8K3M9QF2YV7X4B6N0CWE5T",
      "filename": "hello.md",
      "tags": ["demo"],
      "updated_at": "2026-06-12T21:00:00Z",
      "score": 2.81
    }
  ],
  "limit": 25,
  "total_estimate": 1,
  "next_cursor": null
}

Search is BM25, OR-matched across terms. There is no phrase or AND syntax in this preview.

5. Read it back

curl -sS "$TUPSHAR_HOST/v1/file/01JZ8K3M9QF2YV7X4B6N0CWE5T" \
  -H "Authorization: Bearer $TUPSHAR_KEY"

200 OK returns the full document including contents.

What's next?

Your first request — full CRUD walkthrough with update and delete
API keys — key management details
HTTP API — complete endpoint reference