Quickstart

Create and claim your first kubbi in under two minutes. You will need an API key — get one from the dashboard after signing up.

1. Create a kubbi

Send a POST request with your content, a content type, a TTL (in seconds), and an optional max_retrievals limit.

curl

bash

curl -X POST https://api.kubbi.ai/api/v1/kubbis \
  -H "Authorization: Bearer kb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "sensitive data here",
    "content_type": "text/plain",
    "ttl_seconds": 3600,
    "max_retrievals": 1
  }'

Python

python

from kubbi import KubbiClient

client = KubbiClient(api_key="kb_your_api_key")
result = client.send(
    content="sensitive data here",
    content_type="text/plain",
    ttl_seconds=3600,
    max_retrievals=1,
)
print(result.claim_url)

TypeScript

typescript

import { KubbiClient } from "@kubbi.ai/sdk";

const client = new KubbiClient({ apiKey: "kb_your_api_key" });
const result = await client.send({
  content: "sensitive data here",
  contentType: "text/plain",
  ttlSeconds: 3600,
  maxRetrievals: 1,
});
console.log(result.claimUrl);

The response includes a claim_url — this is what you pass to the consumer.

Response

json

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "claim_url": "https://api.kubbi.ai/r/abc123xyz",
  "claim_token": "abc123xyz",
  "status": "active",
  "content_type": "text/plain",
  "max_retrievals": 1,
  "metadata": null,
  "created_at": "2026-03-28T12:00:00.000Z",
  "expires_at": "2026-03-28T13:00:00.000Z"
}

2. Share the claim URL

Pass only the claim URL to the consumer through whatever channel connects you — a webhook, queue message, MCP tool result, orchestrator payload, or even a Slack message. The sensitive data never leaves kubbi until the consumer claims it.

3. Inspect (optional)

The consumer can preview metadata without consuming the payload.

bash

curl https://api.kubbi.ai/r/abc123xyz

Response· json

{
  "status": "active",
  "content_type": "text/plain",
  "max_retrievals": 1,
  "retrieval_count": 0,
  "metadata": null,
  "created_at": "2026-03-28T12:00:00.000Z",
  "expires_at": "2026-03-28T13:00:00.000Z",
  "claim": {
    "url": "https://api.kubbi.ai/r/abc123xyz/claim",
    "method": "POST",
    "description": "POST to this URL to retrieve the content. This counts as a retrieval."
  }
}

4. Claim the payload

The consumer claims the payload with an empty POST — no API key and no request body required. If max_retrievals is reached, the payload is burned immediately.

bash

curl -X POST https://api.kubbi.ai/r/abc123xyz/claim

Response· json

{
  "content": "sensitive data here",
  "content_type": "text/plain",
  "metadata": null,
  "created_at": "2026-03-28T12:00:00.000Z",
  "expires_at": "2026-03-28T13:00:00.000Z"
}

For application/json kubbis, the content field is parsed JSON (an object or array). For other content types it is a string.

5. Send multiple files in one kubbi

Bundle multiple files into a single kubbi package. The consumer gets everything from one claim URL. File count and size limits depend on your plan.

bash

curl -X POST https://api.kubbi.ai/api/v1/kubbis \
  -H "Authorization: Bearer kb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "name": "config.json",
        "content": "{\"env\":\"prod\",\"region\":\"us-east-1\"}",
        "content_type": "application/json",
        "role": "config"
      },
      {
        "name": "instructions.md",
        "content": "# Deploy\nRun the deploy script with these settings.",
        "content_type": "text/markdown",
        "role": "instructions"
      }
    ],
    "ttl_seconds": 3600,
    "max_retrievals": 1
  }'

Response· json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "claim_url": "https://api.kubbi.ai/r/pkg456xyz",
  "claim_token": "pkg456xyz",
  "status": "active",
  "file_count": 2,
  "total_size_bytes": 142,
  "max_retrievals": 1,
  "metadata": null,
  "created_at": "2026-03-28T12:00:00.000Z",
  "expires_at": "2026-03-28T13:00:00.000Z"
}

When the consumer claims a package kubbi, all files are returned in a single response. Text files ( text/* and application/json) are returned as UTF-8 strings. Binary files are base64-encoded with an encoding: "base64" field.

What happens next

If the last allowed retrieval was used, the kubbi transitions to burned status and the payload is permanently wiped. Any further claim attempts return 410 Gone.
If retrievals remain, the payload stays available until max_retrievals is reached or the TTL expires.
The producer can delete the kubbi early at any time via DELETE /api/v1/kubbis/:id.