API changelog

Additive changes to the public developer API, newest first. The compatibility rules are in api-v1-policy.md; the machine-readable contract is v1-openapi.json.

2026-09 — Business facts cite like any source

Additive; existing callers are unaffected.

• A citation's source_type may now be fact: one of the organization's own maintained business facts (Knowledge › Business), with source_id fact:<id>, source_name Business fact: <topic>, the whole statement as excerpt, and no source_location (a fact has no link). Answers cite a fact with a [Cn] marker like any other evidence. Per api-v1-policy.md, clients treat an unknown enum value as a plain source.

2026-07 — Developer-experience release

All changes are additive; existing callers are unaffected.

New endpoints

• GET /api/v1/openapi.json — the curated public OpenAPI 3.1 spec (only the /api/v1 surface; the uncurated internal schema is no longer served).

• GET /api/v1/docs — interactive Swagger UI over the curated spec.

• GET /api/v1/ingest/{article_id} — editorial status of a note saved via POST /v1/ingest (draft | approved | verified, live vs in review). Ingest was write-only before.

• GET /api/v1/creations — cursor-paginated list of the organization's API-enabled Creations (per-Creation API-channel opt-in honored).

• POST /api/v1/conversations — open a help-desk conversation from an external system on a customer's behalf (organization key, helpdesk scope).

Headers

• Every API-key response now carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (the tighter of the per-key/per-org minute budget). SSE responses are decorated too.

• The automation customer upsert now correctly sets the documented X-Idempotent-Replay: true header on an idempotent replay.

New request parameters

• POST /api/v1/answer now accepts reasoning (auto/off/light/standard/deep — model thinking depth, independent of effort) and model (a per-request model override, permitted only when it is org-allowed or the answering agent's own configured model, else 400). This brings /v1/answer to full parity with POST /v1/agents/{agent_id}/answer; /answer (optionally with agent) is now the canonical answer endpoint and the per-agent path remains a permanent equivalent. Existing /answer callers are unaffected (both are optional).

Aliases & scope widening

• POST /api/v1/agents/{agent_id}/answer accepts effort / mode as permanent aliases for answer_effort / answer_mode, matching the generic /v1/answer vocabulary. POST /api/v1/answer likewise accepts answer_effort / answer_mode; the canonical spelling wins if both are sent.

• GET /api/v1/agents now accepts a key with the retrieve or answer scope (previously answer only), so a retrieve-only key can enumerate the agent slugs its endpoints take.

Discovery & docs

• The GET /api/v1 discovery document now lists the complete top-level surface — including capture, capture-defaults, skills list/run, drive/step, GET /agents and GET /me — plus an automation subtree pointer, spec/docs pointers (specs), and a policies block (compatibility promise, changelog, rate-limit headers).

• Presign responses on upload surfaces are self-describing (resumable_url/protocol/headers/chunk_size), so clients no longer hard-code the storage provider's resumable-upload quirk.