Conventions

These conventions apply across every Developer API endpoint. Reading them once means each endpoint page can stay focused on its own parameters and shapes.

JSON everywhere

Request and response bodies are JSON (Content-Type: application/json), with one exception: document upload uses multipart/form-data (see the Knowledge documents endpoints). All timestamps are ISO-8601 strings in UTC, e.g. 2026-06-07T12:34:56Z.

Cursor pagination

List endpoints return a cursor-paginated page, never an offset/page-number scheme. The wrapper is always the same shape:

{
  "data": [ /* the items on this page */ ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImFndF8xMjMifQ"
}

Control paging with two query parameters:

Treat next_cursor as an opaque value — never parse, construct, or modify it. To walk every page, keep requesting with the previous response’s next_cursor until has_more is false:

# First page
curl "https://cuneiform.chat/api/developer/v1/agents?limit=50" \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"
 
# Next page
curl "https://cuneiform.chat/api/developer/v1/agents?limit=50&cursor=eyJpZCI6ImFndF8xMjMifQ" \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

A malformed cursor returns 400 invalid_request_error (invalid_cursor).

Idempotent requests

Mutating POST requests accept an optional Idempotency-Key header so a retry — after a network error or timeout — never performs the operation twice.

curl -X POST https://cuneiform.chat/api/developer/v1/agents \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c4b7a-2e3d-4f5a-8b6c-1d2e3f4a5b6c" \
  -d '{ "name": "Support Bot", "configuration": { "model": "gpt-4o-mini", "system_prompt": "You are helpful." } }'

How it works:

• Generate a unique key per logical operation (a UUID is ideal) and send it with the request.
• A repeated request carrying the same key within 24 hours replays the original stored response instead of executing the operation again.
• Keys are scoped to your organization.
• After 24 hours the key expires; a request with an expired key is treated as new.

Idempotency-Key is honoured on the blocking agent-query path but ignored on the streaming (stream: true) path.

Deny-by-default responses

Response bodies expose only the fields documented on each endpoint page. They never include internal identifiers, storage internals, LLM provider/model strings, or cost figures. If a field is not in the documented shape, the API does not return it.

Changelog

v1 is the current, stable contract. Changes are additive — new fields and new endpoints may appear, but existing fields are never removed or repurposed within v1.