Payloads and files

kubbi supports two payload shapes: a single content item or a multi-file package. Both use the same POST /api/v1/kubbis endpoint with different request bodies.

Single content

The simplest case. One piece of data with one content type:

• text/plain
• application/json
• text/markdown
• text/csv

Examples: a tool result encoded as JSON, a markdown summary, a CSV report.

Multi-file packages

For when the handoff is more than one file. Each file has its own name, content type, and optional role. The whole package is delivered under a single claim URL.

{
  "files": [
    {
      "name": "config.json",
      "content": "{\"env\":\"prod\"}",
      "content_type": "application/json",
      "role": "config"
    },
    {
      "name": "notes.md",
      "content": "# Notes\nDeploy instructions.",
      "content_type": "text/markdown",
      "role": "instructions"
    }
  ],
  "ttl_seconds": 3600,
  "max_retrievals": 1
}

File roles

Each file in a package can declare a role, which downstream agents use to know what each file is for:

• instructions: what to do with the rest
• data: the primary payload
• context: supporting information
• config: configuration for the consumer
• attachment: supplementary files

Roles are optional but recommended for agent workflows.

Text vs binary files

Text files (text/* and application/json) pass content as a UTF-8 string. Binary files (e.g. image/png) pass base64-encoded content with encoding: "base64".

Limits

File count and total package size depend on your plan tier.

Choosing between single and multi-file

Use a single-content kubbi when one type of data covers the handoff. Use a multi-file package when:

• Multiple artifacts move together
• A consumer needs context alongside the data
• Mixing structured and binary data in one delivery

For full request/response shapes, see Create a kubbi and Create a files kubbi.