API at a glance

Conventions and the endpoint map. The machine-readable OpenAPI spec is the field-by-field reference; these docs teach the flows.

Conventions

• Base URL https://api.cloud.ingram.tech: everything under /v1.
• Headers: Authorization: Bearer <token> (Auth & tokens), plus IC-Api-Version: 2026-05-01 to pin the request/response vocabulary. 2026-05-01 is the only live version today. Omit the header and you get the latest; send one we don't know and the request is refused with unsupported_api_version. Every response echoes the version it served.
• Errors: the OpenAI-standard envelope, always — so the openai SDK and any OpenAI-compatible client parse our failures unchanged:

{ "error": { "message": "…", "type": "invalid_request_error",
             "param": null, "code": "model_key_missing" } }

Match on code (our stable slug); type is the OpenAI category (invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error). Every possible code is enumerated on the Error schema in the OpenAPI spec — the catalog to generate exhaustive client handling from. The request id is the X-Request-Id response header — log it; show message to humans.

• Idempotency: send an Idempotency-Key header on creates; replays return the original response instead of duplicating. This covers streaming run creation too: a retried key returns a run.duplicate pointer rather than starting a second run. Resources with a natural key also upsert on it: re-POST /v1/smiths with an existing live external_id returns that smith (200) rather than erroring.
• One turn per smith: a smith runs one turn at a time, on every run surface — its memory is a single doc shared by all its conversations. A second concurrent run returns 400 conversation_locked; retry in a few seconds. See one run at a time.
• Two dialects, one rule: OpenAI-mirrored resources (/v1/files, /v1/vector_stores, /v1/conversations, /v1/embeddings, and the model surfaces) speak the OpenAI dialect end-to-end — unix-second timestamps, 200 on create, 200 with a *.deleted ack on delete, and the OpenAI list envelope. Every other resource is native — ISO-8601 timestamps, 201 on create, 204 on delete, and the keyset list envelope.
• Pagination, native dialect: list endpoints take limit + cursor and return { data, next_cursor, has_more }, newest first. The cursor is opaque — pass the previous page's next_cursor straight back; never parse it. Pull the next page while has_more is true. The run and event feeds add their own filters (since, status, external_id_prefix, …) on top of the same cursor. Fixed-size config lists (providers, model keys, the catalogs) return bare { data } — they are bounded by construction.
• Pagination, OpenAI dialect: lists take limit + order + after (an object id) and return { object: "list", data, first_id, last_id, has_more }; pass last_id back as after while has_more is true.
• Filtering: GET /v1/smiths filters by exact external_id, customer_id, or agent_id, and segments by external_id_prefix (matches one namespace, e.g. anon:). GET /v1/runs takes the same external_id_prefix to pull one segment's conversation history (plus smith_id, agent_id — every run across one agent's smiths — and status).
• Ids: prefixed and sortable: smt_ (smith), agt_ (agent), run_, thr_, cnv_ (conversation), apr_, evt_, cus_, trc_. A run and its trace share a suffix (run_X ↔ trc_X). Thread ids are yours if you pass them, minted with thr_ if you don't.
• Limits: no published rate limits yet (fair use); synchronous runs hold the connection for the whole turn, so prefer streaming for long ones.

Endpoint map

Early-access surfaces

One resource appears in scopes and usage breakdowns but is early access and not yet documented here: trace ingestion (POST /v1/traces:ingest: push your own spans from an external runtime, optionally tagged with an app_id that group_by=app then attributes usage by). Ask us before building on it.

Two things to know if you already do. Ingesting the same span_id twice is a no-op on the trace's totals, so an at-least-once exporter can retry safely. And a span you don't attribute to a smith produces a trace with smith_id: null — readable with a tenant-admin token, never with a smith token.

Using the OpenAPI spec

GET https://api.cloud.ingram.tech/openapi.json: feed it to your codegen or API client of choice. The spec is generated from the live API, so it's always in sync with the deployment. (https://cloud.ingram.tech/docs/openapi.json redirects here, if you have it wired up already.)

It covers every endpoint this table lists — including the ones that aren't plain JSON in and out. Streaming turns publish both bodies of the one response (text/event-stream and application/json, chosen by stream); uploads publish their multipart/form-data shape; downloads publish application/octet-stream; the browser endpoints publish their redirects; and the provider webhooks publish what a Slack, Meta, Discord, Telegram or Stripe request URL receives. If an endpoint answers it, the spec describes it.