# The-Code API guide for AI agents

This document is the machine integration contract for coding agents, orchestration frameworks, autonomous clients, and generated applications. The-Code is a per-user, OpenAI-compatible AI gateway hosted on Azure.

The agent must receive credentials through an authorized secret mechanism. Never request that a user paste a The-Code API key, provider credential, access token, prompt corpus, or customer data into chat.

## Connection contract

Public documentation: `https://thecodeapi.com/docs`. The public Streamable HTTP MCP
server at `https://api.thecodeapi.com/mcp` provides integration documentation, examples,
endpoint schemas, and structural request checks without authentication. Never
send credentials to this documentation server. It does not execute inference or
return account-specific catalogs; use authenticated `/v1/models` for discovery.

Support: [Support@the-code.org](mailto:Support@the-code.org). Include a request ID
and a sanitized description; do not send credentials or customer content.

```text
THE_CODE_API_BASE_URL=https://api.thecodeapi.com/v1
THE_CODE_API_KEY=<secret user key beginning tca_test_ or tca_live_>
```

Every gateway request sends:

```http
Authorization: Bearer <THE_CODE_API_KEY>
Content-Type: application/json
```

Do not send upstream provider credentials. Do not place the user key in source code, prompts, URLs, logs, exceptions, traces, analytics, tool output, or generated responses.

## Required workflow

1. Load this guide or `https://api.thecodeapi.com/llms.txt`.
2. Obtain the base URL and user key from runtime configuration or a secret manager.
3. Call authenticated `GET /v1/models`.
4. Select only a returned model whose capabilities fit the task.
5. Make the request with bounded output, a correlation ID, and an idempotency key when retry may occur.
6. Preserve response routing headers and usage metadata without recording sensitive content.
7. Refresh model discovery after routing errors or configuration changes.

## Live model discovery

```http
GET /v1/models
Authorization: Bearer <THE_CODE_API_KEY>
```

The response is authoritative for the calling key. It applies current platform approval, active credentials, the user's enabled-model policy, aliases, and capability policy. Disabled models are intentionally absent. Never construct an inventory from documentation, screenshots, portal scraping, an upstream catalog, or a previous response.

Never hard-code a model ID as permanently available. Refresh live discovery after a routing error or administrator configuration change.

Kimi.ai models use the provider prefix `kimi/`. Select the exact ID and request
contract returned by the gateway; do not infer supported parameters or model
availability from the upstream Kimi catalog. Continue using the gateway URL and
The-Code API key, with provider credentials managed by the administrator.

Each exposed model follows the OpenAI list shape and includes a complete, revisioned request contract for its advertised endpoint. Chat models publish positive context/output limits plus caller-specific managed and hard output ceilings. Use `chat` for Chat Completions or Responses and `embeddings` for embeddings; an incomplete contract is not exposed.

Use an exact returned model ID when exact routing is required. Use a returned alias only when administrator-controlled routing is acceptable. Never silently substitute a different model after an exact ID fails.

## Chat Completions

```http
POST /v1/chat/completions
Authorization: Bearer <THE_CODE_API_KEY>
Content-Type: application/json
Idempotency-Key: <stable logical operation ID>
X-Request-ID: <caller correlation ID>

{
  "model": "<ID returned by /v1/models>",
  "messages": [
    {"role": "system", "content": "Follow the application policy."},
    {"role": "user", "content": "Complete the task."}
  ],
  "stream": false
}
```

For non-streaming calls, accept leading JSON-valid whitespace before the final document. Do not treat it as a malformed response.

For streaming calls, parse server-sent events incrementally. Ignore comment frames such as `: ping`, process each `data:` frame, and stop only after `data: [DONE]`. Do not concatenate SSE framing and attempt to parse it as one JSON document.

## Responses and embeddings

`POST /v1/responses` supports the documented non-streaming subset, including `model`, `instructions`, `input`, `max_output_tokens`, `temperature`, tools, and text format. Do not assume unsupported stateful or background behavior; inspect OpenAPI before generating code.

`POST /v1/embeddings` requires a returned model advertising the `embeddings` capability. Preserve input ordering and validate the number of returned vectors.

## Function calling controls and replay

Both Chat Completions and the non-streaming Responses subset accept
`tool_choice` and `parallel_tool_calls`. Check the exact model's
`request_contract.parameters.<parameter>.supported` and `.values` first;
aliases publish the intersection of their targets. `tool_choice` values are
`auto`, `none`, `required`, and `function` (the last denotes a named object,
not a string to send). Chat names a function with
`{"type":"function","function":{"name":"weather"}}`; Responses uses
`{"type":"function","name":"weather"}`. The function must appear in `tools`.

Omit controls to preserve provider defaults. `parallel_tool_calls: true`
permits multiple calls in one response; `false` requires at most one.
Gemini, Kimi, Ollama, and Bedrock Converse do not expose a single-call
guarantee here: `false` returns HTTP 400 `unsupported_parameter`. Anthropic
forced-tool restrictions vary by model. Its generic `json_object` mode
cannot combine with explicit tool selection or parallel=true.
Ollama currently exposes only `tool_choice: "auto"`: its server implementation
does not enforce the other choices.

The application executes custom functions. Replay the entire assistant
message and one tool result for every returned ID before continuing.
Preserve `reasoning_content`, assistant `extra_content`, and each tool call's
`extra_content` verbatim, including through SDK serialization. They carry
Gemini thought signatures and Anthropic signed thinking required for later
turns. For streamed calls, accumulate argument fragments by call index and
retain the final assistant metadata delta. For Responses, replay output items
unchanged and add matching `function_call_output` items. Keep a tool loop on
the same exact provider/model. See [API guide](https://api.thecodeapi.com/docs/api-guide.md#function-tools).

## Idempotency and correlation

Use a stable `Idempotency-Key` for a logical operation that may be retried. Reuse the same key only with byte-equivalent request semantics. A different body with the same key returns `409`.

For non-streaming work that may exceed an HTTP proxy deadline, send
`Prefer: respond-async`. The gateway returns `202` with a `status_url`. Poll that
URL using the same API key, honoring `Retry-After`, until it returns the final
validated completion or a typed terminal error. Do not change the model,
payload, schema, catalog revision, or idempotency key while polling.

Send `X-Request-ID` when the application has a correlation ID. Record returned `X-Request-ID`, `X-The-Code-Provider`, `X-The-Code-Model`, and `X-Idempotent-Replay` metadata. Never include secrets or sensitive content in identifiers.

## Credits and limits

Paid platform traffic consumes the key owner's user wallet. Customer applications cannot grant, transfer, or allocate credits.

When an inference request omits `max_tokens`, `max_completion_tokens`, or
`max_output_tokens`, The-Code applies the caller's managed output policy. The
platform default is 16,384 tokens and may be overridden by organization,
project, or API-key policy. The effective ceiling is then clamped to the live
model contract, remaining context, and any hard per-request policy. This is a
billing and execution guardrail; it is neither unlimited output nor a promise
that the model will consume the full allowance.

Successful responses report `X-The-Code-Output-Policy` (`managed` or
`explicit`) and `X-The-Code-Effective-Max-Tokens`.

Optionally send:

```http
X-The-Code-Max-Credits: <positive decimal ceiling>
```

The gateway rejects a request before dispatch when its estimate exceeds the ceiling. User balance, user/model status, key suspension, deletion, and expiry can deny an otherwise valid request.

## Reasoning and token safety

Send `reasoning_effort` only when the selected model supports it. Priority is explicit request, key default, model default, then platform default. Unsupported combinations return `400`; do not remove safety controls merely to force acceptance.

Keep prompt, tools, images, expected completion, and a safety margin below a known context limit. Keep output below a known maximum. If limits are unknown, start conservatively and handle validation errors explicitly.

## Error envelope

Errors follow an OpenAI-style envelope:

```json
{
  "error": {
    "message": "Model or alias is unavailable",
    "type": "routing_error",
    "param": null,
    "code": "routing_error",
    "request_id": "req_..."
  }
}
```

Retry rules:

- Never retry `400`, `401`, `402`, `403`, `404`, or `409` unchanged.
- Retry eligible `429`, `502`, `503`, and `504` responses only with bounded exponential backoff and jitter.
- Honor `Retry-After` when present.
- Reuse the same idempotency key for the same logical operation.
- Cap attempts and total elapsed time.
- If the final outcome is indeterminate, query application history or ask an authorized human; do not submit a new paid operation blindly.

## User and credential safety

- Do not send `X-Organization-ID`; user tenancy is derived from the API key or Microsoft identity.
- Treat cross-user `404` as final; do not probe neighboring identifiers.
- Never attempt customer impersonation or use workforce administrator tokens on customer routes.
- Never expose credentials, prompts, responses, uploaded bodies, or signed media URLs.
- Do not cache short-lived download URLs. Use the authenticated content URL when needed.
- Redact authorization, cookies, and request bodies from diagnostic output.

## Manual versus agent configuration

An agent may generate application configuration, SDK code, environment-variable templates, health checks, and integration tests. It must not create credentials, grant credits, approve models, change pricing, or weaken tenant policy unless an explicitly authorized control-plane workflow grants that action.

For manual setup, direct the user to the Human guide. For exact schemas, read `https://api.thecodeapi.com/api/openapi.json`. When documentation and a live authenticated response differ, prefer live discovery and OpenAPI for the deployed version.

## Videos

Video operations are exposed as a managed platform capability. Use only the routes and schemas present in the deployed OpenAPI document. Supply a stable idempotency key for generation submissions, poll the documented status resource, and download completed files only through authenticated content URLs.

Do not infer or expose the upstream implementation. Do not cache upstream URLs. Treat prompts, source media, generated files, and metadata as sensitive tenant content subject to retention policy.

## Integration pseudocode

```text
load base_url and api_key from secrets
models = GET base_url + "/models" with bearer api_key
candidate = choose a returned model with the required capability

operation_id = stable application identifier
attempt = 0
while attempt < configured_limit:
    response = POST base_url + "/chat/completions"
        Authorization: Bearer api_key
        Idempotency-Key: operation_id
        X-Request-ID: safe correlation id
        body.model: candidate.id

    if success:
        retain request/routing/usage metadata
        return parsed result
    if response is not retryable:
        return structured error
    wait bounded exponential backoff with jitter
    attempt += 1

return indeterminate/retry-exhausted error
```

## Agent checklist

- Base URL ends in `/v1`.
- Key comes from a secret mechanism.
- Models are discovered live with the same key.
- Selected capability matches the endpoint.
- Request sizes are bounded.
- Retryable operations use a stable idempotency key.
- SSE comments and `[DONE]` are handled correctly.
- Retry attempts and total time are capped.
- Routing and request IDs are retained.
- Secrets and sensitive content are never logged.
- Cross-tenant identifiers are never probed.

## Authoritative links

- Human guide: `https://api.thecodeapi.com/docs/human-guide.md`
- Agent guide: `https://api.thecodeapi.com/docs/ai-agent-guide.md`
- Documentation index: `https://api.thecodeapi.com/llms.txt`
- OpenAPI: `https://api.thecodeapi.com/api/openapi.json`
- Swagger: `https://api.thecodeapi.com/api/docs`
- Live models: `https://api.thecodeapi.com/v1/models`
- Readiness: `https://api.thecodeapi.com/health/ready`