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/chat | POST /public/v1/<namespace>/<slug>/chat | POST /public/v1/chat/completions | |
|---|---|---|---|
| What answers | A published agent, named by agent_id | The same agent, addressed by the registry path shown when it was published | A model, named by model or chosen by tier |
| Knowledge, tools and guardrails | The agent's own, as configured in Studio | The same | None from an agent; the gateway's output rails still apply |
| Memory across calls | A session, passed as session_id | The same | None; send the whole conversation in messages each time |
| Request shape | Katonic's: agent_id, messages, session_id, context, model | The same without agent_id | OpenAI's chat completion request |
| Streaming | Yes, with stream set to true | No | Yes, with stream set to true |
| Scope | Chat | Chat | Chat |
| Reach for it when | You want the agent as built, from your own application | You were handed the address at publish time | You 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
- Python
- TypeScript
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?"}]}'
import requests
BASE = "https://<your tenant host>/public/v1"
HEADERS = {"Authorization": "Bearer kapi_..."}
r = requests.post(f"{BASE}/chat", headers=HEADERS, json={
"agent_id": "support-assistant",
"messages": [{"role": "user", "content": "What does our refund policy say about digital goods?"}],
})
r.raise_for_status()
print(r.json()["message"]["content"])
const BASE = "https://<your tenant host>/public/v1";
const headers = { Authorization: "Bearer kapi_...", "Content-Type": "application/json" };
const r = await fetch(`${BASE}/chat`, {
method: "POST",
headers,
body: JSON.stringify({
agent_id: "support-assistant",
messages: [{ role: "user", content: "What does our refund policy say about digital goods?" }],
}),
});
if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
const reply = await r.json();
console.log(reply.message.content);
Then the same question to a model, with no agent in between:
- cURL
- Python
- TypeScript
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?"}]}'
r = requests.post(f"{BASE}/chat/completions", headers=HEADERS, json={
"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?"},
],
})
r.raise_for_status()
body = r.json()
print(body["choices"][0]["message"]["content"], "| served by", body["served_model"])
const c = await fetch(`${BASE}/chat/completions`, {
method: "POST",
headers,
body: JSON.stringify({
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?" },
],
}),
});
const completion = await c.json();
console.log(completion.choices[0].message.content, "| served by", completion.served_model);
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. modelon the agent route names a model for this turn, subject to the tenant's model access rules;contextis 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 504UPSTREAM_TIMEOUT. Withstreamset, the longer generation budget applies, and a turn that outruns the agent's own limit of about five minutes ends with aRUN_ERRORevent. 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_reasonset tocontent_filterand aguardrailobject. - Setting
streamon 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
detailand nocode. Any text produced before the failure is discarded. - On the current build an agent created through
POST /public/v1/agentsis saved but cannot answer a turn; chat with agents built in Studio until that is fixed.
Troubleshooting
- 401 with
AUTH_ERRORandInvalid 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 foundon 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:messageshad no entry with text, so nothing was asked and no model was called. - 502 whose
detailis 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_fallbackandfallback_reason; the primary was unhealthy, keyless or not a candidate for the caller's lane.
The same conversation elsewhere
Related
- Chat from your application, the session-by-session walkthrough
- Use an OpenAI client library
- Chat and completions