Claim URLs

When a producer creates a kubbi, the API returns a claim_url. This URL is the only thing the consumer needs to inspect and claim the payload — whether it is a single piece of content or a multi-file package.

Claim URL vs. claim token

These two terms refer to different things:

Term	What it is	Example
claim_url	The full URL returned to the producer	https://api.kubbi.ai/r/abc123xyz
claim_token	The unguessable token at the end of the URL	abc123xyz

The claim_url is a capability URL — possession of it is sufficient to inspect or claim the kubbi. No API key or account is needed. The consumer hits the URL; kubbi extracts the claim_token from the path internally.

How to pass the claim URL

How the producer delivers the claim URL to the consumer is outside the scope of kubbi. kubbi handles secure storage and retrieval — not the communication channel between actors. The URL is just a string and travels over whatever channel already connects the two actors.

Distribution patterns

1. A2A Message (Agent-to-Agent Protocol)

Actor A sends an A2A message to Actor B's agent endpoint with the claim URL in the message body.

When it fits: Both actors are A2A-compatible agents with known, reachable endpoints.

Example A2A message· json

{
  "task": "summarise_research",
  "input_type": "kubbi",
  "claim_url": "https://api.kubbi.ai/r/abc123xyz",
  "instructions": "Summarise into three bullet points."
}

2. MCP Tool Call Result

Actor A is an MCP tool that returns the claim URL as part of its tool result. The MCP host passes it into the LLM context. The LLM then invokes Actor B with the claim URL as a parameter.

When it fits: Both actors are tools in the same MCP-hosted session.

Example flow· text

Tool call:  kubbi_send({ content: "...", ttlSeconds: 600 })
Tool result: { "claimUrl": "https://api.kubbi.ai/r/abc123xyz" }

LLM passes to next tool:
Tool call:  process_data({ claim_url: "https://api.kubbi.ai/r/abc123xyz" })

3. Workflow Orchestrator Payload

Actor A completes a step in a workflow (LangGraph, Temporal, Prefect, Airflow, n8n, etc.) and writes the claim URL into the step's output. The orchestrator passes it as input to the next step.

When it fits: Both actors are nodes or tasks in the same workflow graph.

Example step output· json

{
  "status": "complete",
  "claim_url": "https://api.kubbi.ai/r/abc123xyz"
}

Works equally well for sequential and fan-out patterns. For fan-out, the orchestrator distributes the same claim URL to multiple downstream steps — each claims up to max_retrievals.

4. Direct API Call

Actor A makes an HTTP call to Actor B's API, including the claim URL in the request body. Common in microservice architectures.

Example request· http

POST https://analytics-service.internal/jobs
Content-Type: application/json

{
  "job_type": "process_dataset",
  "claim_url": "https://api.kubbi.ai/r/abc123xyz",
  "submitted_by": "etl-pipeline-v2"
}

5. Queue Message

Actor A publishes a message to a queue (SQS, RabbitMQ, Kafka, Redis pub/sub) containing the claim URL. Actor B consumes it on its own schedule.

When it fits: The two actors operate at different speeds and are decoupled by design.

Example queue message· json

{
  "event": "research_cycle_complete",
  "claim_url": "https://api.kubbi.ai/r/abc123xyz",
  "produced_at": "2026-03-22T02:00:00Z",
  "ttl_expires_at": "2026-03-22T03:00:00Z"
}

Including ttl_expires_at lets Actor B detect whether the kubbi has already expired before attempting a claim.

6. Webhook Delivery

Actor A POSTs to Actor B's registered webhook endpoint with the claim URL in the body. Common across organisational boundaries.

Example webhook payload· json

{
  "event_type": "data.ready",
  "claim_url": "https://api.kubbi.ai/r/abc123xyz",
  "source": "company-a-research-pipeline",
  "timestamp": "2026-03-22T02:15:00Z"
}

7. Shared Task Object

Actor A writes the claim URL into a record in an external system both actors can access — a task tracker, database row, shared document, or CRM record. Actor B reads it on its own schedule.

Example: writing to a jobs table· sql

INSERT INTO jobs (job_type, claim_url, status, created_at)
VALUES ('weekly_report', 'https://api.kubbi.ai/r/abc123xyz', 'pending', NOW());

This pattern is particularly useful when a human is one of the actors — a reviewer can see the claim URL in a task ticket and claim the kubbi from a browser.

Security note

Treat claim URLs as secrets. Anyone who has the URL can claim the payload. Share them only through channels appropriate for the sensitivity of the data. kubbi secures the storage and claim lifecycle — the security of the delivery channel is your responsibility.