API Conventions

The current backend is not yet a polished public API, but it already has clear conventions you should follow when building against it. This page documents those conventions instead of pretending the product already ships a generic pagination-first REST surface.

Organization scoping

Most platform routes are scoped to an organization and expect an organizationId either:

• in the query string for reads, or
• in the request body for writes

curl "$API_BASE/api/runs?organizationId=org_123" \
  -H "Authorization: Bearer $TOKEN"

Identifiers and timestamps

Current resource records typically expose:

• string identifiers such as id, promptKey, tool_key, or agent_key
• ISO timestamp strings such as createdAt, updatedAt, or completedAt
• version objects instead of raw version numbers when a published version exists

When a resource can be addressed by both a database id and a stable key, the current UI usually shows both.

Request bodies

Write operations are JSON-based and usually follow this shape:

{
  "organizationId": "org_123",
  "name": "Returns eligibility",
  "description": "Reusable prompt for returns decisions"
}

Complex write routes use nested JSON for schemas, mappings, transitions, or runtime config. For example:

• tool configs and input schemas
• prompt version variables schemas
• agent steps and transitions
• realtime event payloads

List responses

Current list routes are mostly simple arrays rather than a universal paginated wrapper:

[
  {
    "id": "prompt_123",
    "name": "Returns eligibility"
  }
]

The notable exception right now is service keys, which already return a cursor-oriented shape:

{
  "items": [],
  "next_cursor": null
}

For now, you should treat pagination and filtering as route-specific rather than globally standardized. The docs will call out any route that behaves differently.