Skip to main content

Agent chat or model completion

Public API

The public API has two front doors for a conversation. The agent routes run an agent exactly as Studio built it, with its knowledge sources, tools, guardrails and memory. The model routes go straight to the AI Gateway and accept the request shape an OpenAI client library already sends. Pick by what should be doing the thinking: the agent, or your own code.

Who can use it: anyone holding an API key with the Chat scope for the agent routes and chat completions, or the Completions scope for text completions. The tenant must be licensed for the public API.

Which route​

POST /public/v1/chatPOST /public/v1/<namespace>/<slug>/chatPOST /public/v1/chat/completions
What answersA published agent, named by agent_idThe same agent, addressed by the registry path shown when it was publishedA model, named by model or chosen by tier
Knowledge, tools and guardrailsThe agent's own, as configured in StudioThe sameNone from an agent; the gateway's output rails still apply
Memory across callsA session, passed as session_idThe sameNone; send the whole conversation in messages each time
Request shapeKatonic's: agent_id, messages, session_id, context, modelThe same without agent_idOpenAI's chat completion request
StreamingYes, with stream set to trueNoYes, with stream set to true
ScopeChatChatChat
Reach for it whenYou want the agent as built, from your own applicationYou were handed the address at publish timeYou bring your own prompt and orchestration, or an OpenAI client library

POST /public/v1/completions is the text completion twin of chat completions, with the same body and the Completions scope.

Quick start​

Both calls below go to https://<your tenant host>/public/v1 with the key as a bearer token. Ask the agent first:

curl -X POST "https://<your tenant host>/public/v1/chat" \
-H "Authorization: Bearer kapi_..." \
-H "Content-Type: application/json" \
-d '{"agent_id": "support-assistant",
"messages": [{"role": "user", "content": "What does our refund policy say about digital goods?"}]}'

Then the same question to a model, with no agent in between:

curl -X POST "https://<your tenant host>/public/v1/chat/completions" \
-H "Authorization: Bearer kapi_..." \
-H "Content-Type: application/json" \
-d '{"tier": "balanced",
"messages": [{"role": "system", "content": "Answer from the policy text you are given."},
{"role": "user", "content": "Digital goods can be refunded within 14 days. Can I return an e-book after a month?"}]}'

What comes back​

The agent route answers with one object: message (an object with role set to assistant and the reply as content), session_id and agent_id, the last echoing what you sent. Only the latest user message in messages is answered on a call (with no user entry, the last entry of any role); the rest of the array is discarded, and earlier turns come from the session, so pass session_id to continue a conversation. See Sessions.

The model route answers with an OpenAI chat completion object, choices[0].message.content and usage, plus fields the gateway adds: tier, provider, served_model and served_provider say what actually answered; model is overwritten with the model served, so it is safe to log; is_fallback, with fallback_from and fallback_reason, is set when the tier's primary model did not serve the call; and guardrail is present only when an output rail blocked, redacted or warned on this turn. See Chat and completions.

Limits and behaviour​

  • The registry-path route answers 404 for an agent that exists but is not published to the API channel, the same as for a missing agent, so a caller cannot confirm an agent exists off its channel.
  • With no agent_id, the tenant's default agent answers the agent route, or its personal-chat agent when none is marked default.
  • model on the agent route names a model for this turn, subject to the tenant's model access rules; context is handed to the agent's run as free-form values.
  • Without stream, the agent route is held to the sixty-second budget, and a turn that takes longer answers 504 UPSTREAM_TIMEOUT. With stream set, the longer generation budget applies, and a turn that outruns the agent's own limit of about five minutes ends with a RUN_ERROR event. Chat completions are always on the longer budget.
  • An input guardrail that refuses the question does not fail the agent route: the refusal arrives as ordinary assistant text with status 200 and no flag. On chat completions the same refusal is marked with finish_reason set to content_filter and a guardrail object.
  • Setting stream on chat completions delivers tokens as the model produces them, unless the guardrail profile has output rails. Then the gateway holds the whole answer so those rails can read it, and sends the events together.
  • When the agent's run fails, the route answers 404 for an agent that could not be found and 502 for anything else, with the run's own error text in detail and no code. Any text produced before the failure is discarded.
  • On the current build an agent created through POST /public/v1/agents is saved but cannot answer a turn; chat with agents built in Studio until that is fixed.

Troubleshooting​

  • 401 with AUTH_ERROR and Invalid or expired API key, but the key works elsewhere: the key lacks the scope this path needs. The gateway checks the scope while validating the key, so a missing Chat or Completions scope looks like a bad key. Create a key with the Chat only or Full access preset.
  • 404 with Agent not found on the registry path: the namespace or slug is wrong, or the agent is not published to the API channel.
  • 200 with an empty message.content: messages had no entry with text, so nothing was asked and no model was called.
  • 502 whose detail is an error message: the agent's run failed and the route relays its error. Open the agent in Studio and run the same question on its Test tab.
  • A completion answers from a different model than you named: read is_fallback and fallback_reason; the primary was unhealthy, keyless or not a candidate for the caller's lane.

The same conversation elsewhere

Describes the platform as of .

Was this page helpful?