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

Load this guide or https://api.thecodeapi.com/llms.txt.
Obtain the base URL and user key from runtime configuration or a secret manager.
Call authenticated GET /v1/models.
Select only a returned model whose capabilities fit the task.
Make the request with bounded output, a correlation ID, and an idempotency key when retry may occur.
Preserve response routing headers and usage metadata without recording sensitive content.
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.

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