API Reference

Endpoint maps, parameters, limits, token accounting, and error shapes for the Terminaili public API.

Quickstart Guides Integrations OpenAPI JSON

Endpoint Map

Public API endpoints are rooted at https://api.terminaili.com/v1.

Endpoint	Method	Use
`/v1/openapi.json`	GET	Read the public OpenAPI contract.
`/v1/chat/completions`	POST	Create OpenAI-compatible chat completions.
`/v1/embeddings`	POST	Create OpenAI-compatible embeddings.
`/v1/models`	GET	List public models and model groups.
`/v1/models/{model_id}`	GET	Inspect one public model.
`/v1/status`	GET	Read public model availability.
`/v1/ready`	GET	Read first-request readiness and setup checks.
`/v1/estimate`	POST	Estimate tokens and cost before execution.
`/v1/agent-capabilities`	GET	Discover agent-client capabilities and generated config URLs.
`/v1/agent-turns`	POST	Create a resumable agent-native coding turn.
`/v1/agent-turns/{request_id}`	GET	Read a resumable agent turn.
`/v1/agent-turns/{request_id}/events`	GET	Resume agent turn events with Server-Sent Events.
`/v1/agent-turns/{request_id}/cancel`	POST	Cancel a running agent turn.
`/v1/agent-tool-batches/plan`	POST	Plan local tool-call execution batches.
`/v1/client-config/opencode`	GET	Generate OpenCode client configuration.
`/v1/client-config/opencode/freshness`	GET	Check saved OpenCode config freshness.
`/v1/client-config/hermes`	GET	Generate Hermes client configuration.
`/v1/client-config/hermes/freshness`	GET	Check saved Hermes config freshness.
`/v1/orchestrations`	GET/POST	List or create hosted multi-agent orchestration runs.
`/v1/orchestrations/{id}`	GET	Read one hosted orchestration run.
`/v1/orchestrations/{id}/events`	GET	Replay hosted orchestration events.
`/v1/orchestrations/{id}/tasks`	GET	List hosted orchestration role tasks.
`/v1/orchestrations/{id}/locks`	GET	List hosted orchestration path locks.
`/v1/orchestrations/{id}/artifacts`	GET	List hosted orchestration artifacts.
`/v1/orchestrations/{id}/candidates`	GET	List merge candidates and review results.
`/v1/orchestrations/{id}/cancel`	POST	Cancel a hosted orchestration.
`/v1/orchestrations/{id}/merge`	POST	Request merge arbitration.
`/v1/orchestrations/{id}/undo`	POST	Request merge undo using checkpoint or rollback artifacts.
`/v1/orchestrations/{id}/tasks/{task_id}/retry`	POST	Retry an eligible role task.
`/v1/files`	GET/POST	List your uploaded files or upload a new file (batch input, fine-tune training data).
`/v1/files/{file_id}`	GET/DELETE	Read or delete one of your uploaded files.
`/v1/files/{file_id}/content`	GET	Download the raw bytes of a previously uploaded file.
`/v1/batches`	GET/POST	List your batch jobs or create a new batch from an uploaded JSONL file. Billed at 50% of realtime per token.
`/v1/batches/{batch_id}`	GET	Read one batch job, including request_counts and the output file id when complete.
`/v1/batches/{batch_id}/cancel`	POST	Request cancellation of a running batch job.
`/v1/solana-rpc/plans`	GET	List Solana RPC access plans.
`/v1/solana-rpc/methods`	GET	List tested Solana RPC methods.
`/v1/solana-rpc/{network}`	POST	Proxy Solana JSON-RPC for mainnet or devnet.
`/v1/projects/{project_id}/box`	GET	Read Project Box documents, usage, and query history.
`/v1/projects/{project_id}/box/documents`	POST	Upload a Project Box document for indexing.
`/v1/projects/{project_id}/box/documents/{document_id}`	GET/DELETE	Read or delete one Project Box document.
`/v1/projects/{project_id}/box/documents/{document_id}/source`	GET	Download a Project Box source document.
`/v1/projects/{project_id}/box/documents/{document_id}/chunks/{chunk_id}`	GET	Read one Project Box source chunk.
`/v1/projects/{project_id}/box/documents/{document_id}/reindex`	POST	Queue Project Box reindexing.
`/v1/projects/{project_id}/box/query`	POST	Ask a cited question over Project Box documents.
`/v1/projects/{project_id}/secrets`	GET	List Project Secrets metadata without returning raw values.
`/v1/projects/{project_id}/secrets/{name}`	PUT/DELETE	Create, rotate, or delete one Project Secret.
`/v1/projects/{project_id}/app-config`	GET	Read app configuration readiness and required secret hints.
`/v1/projects/{project_id}/jobs`	GET/POST	List or create background job definitions.
`/v1/projects/{project_id}/cron`	GET/POST	List or create cron schedules that enqueue job runs.
`/v1/projects/{project_id}/jobs/{job_id}/runs`	POST	Start a manual job run.
`/v1/projects/{project_id}/job-runs`	GET	List job run history.
`/v1/projects/{project_id}/job-runs/{run_id}`	GET	Read one job run with logs and status.
`/v1/projects/{project_id}/job-runs/{run_id}/retry`	POST	Retry a failed or completed job run.
`/v1/projects/{project_id}/queues/{queue_name}/messages`	GET/POST	List or enqueue JSON queue messages.
`/v1/projects/{project_id}/webhooks`	GET/POST	List or create event webhook subscriptions.
`/v1/projects/{project_id}/webhooks/{webhook_id}/disable`	POST	Disable one webhook subscription.
`/v1/projects/{project_id}/webhooks/{webhook_id}/rotate-secret`	POST	Rotate and reveal a webhook signing secret once.
`/v1/projects/{project_id}/webhook-deliveries`	GET	List webhook delivery attempts and retry state.
`/v1/projects/{project_id}/webhook-deliveries/{delivery_id}/replay`	POST	Queue a replay for one webhook delivery.
`/v1/projects/{project_id}/events`	GET	Read supported event names and recent project events.
`/v1/projects/{project_id}/databases`	GET/POST	List or attach/provision Postgres handoff databases.
`/v1/projects/{project_id}/databases/{database_id}`	GET	Read one database attachment without exposing the full URL.
`/v1/projects/{project_id}/databases/{database_id}/rotate-credentials`	POST	Rotate DATABASE_URL through Project Secrets.
`/v1/projects/{project_id}/databases/{database_id}/attach-hosted-app`	POST	Attach a database to a hosted app.
`/v1/usage`	GET	List public-safe usage summaries.
`/v1/account/meter-events`	GET	List account meter events.
`/v1/account/meter-events/export`	GET	Export account meter events.
`/v1/request-history`	GET	List sanitized retained request history.
`/v1/account/provider-credentials`	GET/POST	List or create provider credentials.
`/v1/account/provider-credentials/{credential_id}`	PATCH/DELETE	Update or delete one provider credential.
`/v1/account/provider-credentials/{credential_id}/test`	GET	Test one provider credential.

Chat Completions

The primary compatibility endpoint for OpenAI SDKs and coding agents.

OpenAPI JSON

POSThttps://api.terminaili.com/v1/chat/completions

AuthAuthorization: Bearer $TERMINAILI_API_KEY

Parameter	Type	Required	Description
`model`	string	Required	Public model id to use, for example TERMINAILI_MODEL.
`messages`	array	Required	OpenAI-compatible chat messages with role and content.
`stream`	boolean	Optional	Set true for Server-Sent Events when the model supports streaming.
`tools`	array	Optional	OpenAI-compatible tool definitions for agentic clients.
`tool_choice`	string \| object	Optional	Let the model choose tools, force one, or disable tools.
`seed`	integer	Optional	Request deterministic sampling where supported.
`stop`	string \| array	Optional	Stop generation before one of the provided sequences.
`response_format`	object	Optional	Request JSON output where the selected model supports it.
`temperature`	number	Optional	Sampling temperature. Use lower values for deterministic coding tasks.
`top_p`	number	Optional	Nucleus sampling control, forwarded when supported.
`max_tokens`	number	Optional	Maximum output tokens for the completion.
`max_completion_tokens`	number	Optional	OpenAI-compatible output-token limit; overrides max_tokens.

Response

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "ipop/coder-balanced",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello. Terminaili is ready."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  },
  "ipop": {
    "request_id": "req_...",
    "cost_usd": 0.00042,
    "cache_hit": false
  }
}

Token Usage

Chat and embeddings responses include OpenAI-compatible usage fields when the model reports them.

Response usage

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "ipop/coder-balanced",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello. Terminaili is ready."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  },
  "ipop": {
    "request_id": "req_...",
    "cost_usd": 0.00042,
    "cache_hit": false
  }
}

Rate Limits

Requests are guarded by body-size, input-size, queued-request, inflight, and per-minute limits.

429 responsesBack off and retry after the retry-after value when present.

Retry safetyUse idempotency-key on retryable chat, embeddings, inference, and agent-turn calls.

Capacity pressure409 or 503 may be retryable when models are queued or temporarily unavailable.

Error Codes

Error bodies include a message, code, request id, retryability, and optional retry timing.

Status	Code	What to do
`400`	bad_request	Fix the JSON body, unsupported parameter, or validation error.
`400`	context_length_exceeded	Shorten input or choose a longer-context model.
`401`	unauthorized	Set Authorization: Bearer $TERMINAILI_API_KEY or the x-api-key header.
`401`	model_not_allowed	Use a model allowed by the API key policy.
`402`	payment_required	Add credit, lower max tokens, or choose a lower-cost model.
`409`	policy_violation	Use a model and route allowed by the API key policy.
`409/503`	capacity_unavailable	Retry safely with idempotency-key; include the request id for support.
`429`	rate_limit_exceeded	Back off and honor retry-after when present.

Embeddings API

Create embedding vectors from a string or batch of strings.

POSThttps://api.terminaili.com/v1/embeddings

Parameter	Type	Required	Description
`model`	string	Required	Public embedding-capable model id.
`input`	string \| string[]	Required	Text or batch of text inputs to embed.
`dimensions`	integer	Optional	Requested embedding dimensions when supported by the selected model.
`encoding_format`	float \| base64	Optional	OpenAI-compatible embedding encoding format.
`metadata`	object	Optional	Public request metadata for routing or reporting.

Embeddings

curl https://api.terminaili.com/v1/embeddings \
  -H "Authorization: Bearer $TERMINAILI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "terminaili/embed-balanced",
    "input": "Embed this sentence for retrieval."
  }'

Models

List, inspect, and choose public model ids without provider or route internals.

Endpoint	Method	Use
`/v1/models`	GET	List usable public models; pass include_unavailable=true for catalog visibility.
`/v1/models/{model_id}`	GET	Read one public model by id.
`/v1/models/health`	GET	Check public model readiness by capability.
`/v1/model-recommendations`	POST	Ask for ranked model ids for a task.

List models

curl https://api.terminaili.com/v1/models

Status & Ready

Use /status for availability and /ready for setup checks.

GEThttps://api.terminaili.com/v1/status

GEThttps://api.terminaili.com/v1/ready

Status

curl https://api.terminaili.com/v1/status

Ready

curl https://api.terminaili.com/v1/ready

Usage

Read public-safe spend, request, and model usage summaries with the same API key.

Endpoint	Method	Use
`/v1/usage`	GET	Read usage summaries scoped to the API key.
`/v1/usage/export`	GET	Export sanitized usage summaries.
`/v1/account/meter-events`	GET	Read account meter events.
`/v1/account/meter-events/export`	GET	Export account meter events.
`/v1/request-history`	GET	Read retained sanitized requests.
`/v1/request-history/export`	GET	Export retained sanitized requests.

Usage summary

curl https://api.terminaili.com/v1/usage \
  -H "Authorization: Bearer $TERMINAILI_API_KEY"

Request History

List, export, replay, or annotate retained sanitized request history.

Endpoint	Method	Use
`/v1/request-history`	GET	List retained sanitized request summaries.
`/v1/request-history/{request_id}`	GET	Read one retained request.
`/v1/request-history/{request_id}/replay`	POST	Replay a retained chat or embeddings request.
`/v1/request-history/{request_id}/feedback`	POST	Attach quality feedback to a retained request.

Request history

curl "https://api.terminaili.com/v1/request-history?limit=25" \
  -H "Authorization: Bearer $TERMINAILI_API_KEY" \
  -H "Content-Type: application/json"

Solana RPC

Read plan metadata, inspect tested methods, and proxy JSON-RPC for mainnet or devnet.

Endpoint	Method	Use
`/v1/solana-rpc/plans`	GET	Read Solana RPC access plans.
`/v1/solana-rpc/methods`	GET	Read tested upstream JSON-RPC methods.
`/v1/solana-rpc/{network}`	POST	Proxy JSON-RPC requests for mainnet or devnet.

Solana RPC

curl "https://api.terminaili.com/v1/solana-rpc/mainnet" \
  -H "Authorization: Bearer $TERMINAILI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getHealth"
  }'

Account API

Export meter events and manage provider credentials for external model provider keys.

Endpoint	Method	Use
`/v1/account/meter-events`	GET	List account meter events.
`/v1/account/meter-events/export`	GET	Export account meter events.
`/v1/account/provider-credentials`	GET/POST	List or create provider credentials.
`/v1/account/provider-credentials/{credential_id}`	PATCH/DELETE	Update or delete one credential.
`/v1/account/provider-credentials/{credential_id}/test`	GET	Run a credential health check.

Provider credential test

curl "https://api.terminaili.com/v1/account/provider-credentials/$CREDENTIAL_ID/test" \
  -H "Authorization: Bearer $TERMINAILI_API_KEY"