# Agent chat or model completion

Choose between running a published agent and calling a model directly, with the request shapes, what each route carries across calls, and what comes back.

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**

```bash
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?"}]}'
```

**Python**

```python

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"])
```

**TypeScript**

```typescript
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**

```bash
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?"}]}'
```

**Python**

```python
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"])
```

**TypeScript**

```typescript
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](/developers/guides/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.

## Related

- [Chat from your application](/developers/guides/chat-from-your-application), the session-by-session walkthrough
- [Use an OpenAI client library](/developers/guides/use-an-openai-client-library)
- Chat and completions

Source: https://docs.katonic.ai/developers/guides/agent-chat-or-model-completion
