Skip to content
Get API Key

Navigation

← Documentation

API Reference

Tangle Router exposes an OpenAI-compatible REST API. Response formats depend on the operation: chat returns JSON or SSE, speech returns audio bytes, and video content returns media. Image edits accept multipart/form-data; transcription accepts JSON with base64 audio in input_audio.data and its format in input_audio.format. Read the OpenAPI contract for typed operations.

Search guides and API reference.

Documentation sections

Base URL

bash
https://router.tangle.tools/v1

Authentication

Pass your API key in the Authorization header:

bash
Authorization: Bearer sk-tan-your-key-here

Prompt Caching

Prompt caching is on by default. Agents, audits, and RAG workloads with repeated prefixes get provider-native cache reads without changing SDKs.

typescript
const completion = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-4-6',
  messages: [
    { role: 'system', content: longStableSystemPrompt },
    { role: 'user', content: 'Use the same context again.' },
  ],
  providerOptions: {
    gateway: {
      caching: 'auto',
      cacheControl: { enabled: true, ttl: '1h' },
    },
  },
})
X-Tangle-Prompt-Cache

miss, read, write, or read_write

usage.prompt_cache

tokens read, tokens written, and USD savings

Opt out per request with providerOptions.gateway.caching = false.

Blueprint Routing

Route requests to Tangle operators running specific Blueprints. Pass as headers or in the request body.

X-Tangle-Routing

"operator" | "provider" | "auto" — control routing target

X-Tangle-Blueprint

On-chain Blueprint ID (uint) — route to operators under this Blueprint

X-Tangle-Service

On-chain service instance ID (uint) — route to a specific service

X-Tangle-Operator

Operator address (0x...) or slug — pin to a specific operator

Endpoints

POST/v1/chat/completions

Create a chat completion. Returns JSON unless stream: true requests SSE.

Request fields (42)
  • modelstringrequired
  • messagesobject[]required
  • streamboolean

    Only true requests SSE. Omitted or false returns a JSON completion.

  • temperaturenumber
  • max_tokensinteger
  • toolsobject[]
  • tool_choicenone | auto | required | object

    Any other string returns 400 invalid_tool_choice; objects are checked by the provider.

  • parallel_tool_callsboolean
  • response_formattext | json_object | json_schema

    Structured output.

  • top_pnumber
  • stopstring | string[]
  • seedinteger
  • ninteger
  • presence_penaltynumber
  • frequency_penaltynumber
  • logit_biasobject
  • logprobsboolean
  • top_logprobsinteger
  • userstring
  • metadataobject
  • storeboolean
  • stream_optionsobject

    Router requests usage on every stream so it can bill; the final chunk carries usage.

  • service_tierflex | priority

    Any other value returns 400 invalid_service_tier.

  • reasoning_effortstring
  • reasoningobject
  • thinkingobject

    Anthropic extended thinking.

  • max_completion_tokensinteger

    0 is accepted only for Anthropic prompt-cache pre-warm requests; other models need at least 1.

  • modalitiesstring[]
  • audioobject
  • predictionobject
  • systemany

    Anthropic-style system prompt.

  • cache_controlobject

    Provider prompt-cache control, sanitized per provider.

  • prompt_cache_keystring
  • prompt_cache_retentionstring
  • prompt_cache_isolation_keystring
  • session_idstring
  • modelsstring[]

    Router: fallback models, tried in order.

  • providerobject

    Router: provider routing preferences (order, only, ignore, max_price, data_collection, ...).

  • gatewayobject

    Router: gateway options.

  • providerOptionsobject

    Router: providerOptions.gateway carries gateway options, including byok and maxPrice.

  • pluginsobject[]

    Router: server plugins such as web search.

  • transformsstring[]

400 Invalid request. error.code identifies the cause; codes include invalid_json, invalid_model, model_not_found, model_not_allowed, invalid_message_role, invalid_tool_choice, invalid_service_tier, invalid_require_model, unsupported_parameters, conflicting_options, max_price_exceeded, no_zdr_providers, zdr_extensions_not_supported, no_train_extensions_not_supported, model_requires_responses_for_tools, model_requires_reasoning_effort_none_for_tools, model_requires_audio_speech_endpoint, preset_not_found, guardrail_blocked, byok_credential_unavailable, byok_operator_conflict, invalid_execution_correlation.

POST/v1/responses

OpenAI Responses API — agentic, tool-using completions.

Request fields (9)
  • modelstringrequired
  • inputstring | object[]
  • instructionsstring
  • streamboolean

    true returns text/event-stream; omitted or false returns JSON.

  • toolsobject[]

    Function tools pass through; Router-run server tools (web search, fetch, image generation) are executed by Router.

  • tool_choiceany
  • textobject

    Output format, including json_schema structured output.

  • previous_response_idstring
  • service_tierflex | priority

    Requested provider service tier. Any other value returns 400 invalid_service_tier.

400 Invalid request. error.code identifies the cause; codes include invalid_json, missing_model, invalid_service_tier, invalid_execution_correlation, no_train_extensions_not_supported, zdr_extensions_not_supported, execution_correlation_required and model_not_allowed (key allow-list), and previous_response_not_supported for chat-served Responses requests. Chat-served requests can also return the chat completions error codes.

POST/v1/messages

Anthropic Messages API — Claude-compatible completions.

Request fields (7)
  • modelstringrequired
  • messagesobject[]
  • systemstring | object[]
  • max_tokensinteger
  • streamboolean

    true returns text/event-stream; omitted or false returns JSON.

  • toolsobject[]
  • service_tierflex | priority

    Requested provider service tier. Any other value returns 400 invalid_service_tier.

400 Invalid request. error.code identifies the cause; codes include invalid_json, missing_model, invalid_service_tier, invalid_execution_correlation, no_train_extensions_not_supported, zdr_extensions_not_supported, execution_correlation_required and model_not_allowed (key allow-list), and previous_response_not_supported for chat-served Responses requests. Chat-served requests can also return the chat completions error codes.

GET/v1/models

Discover model IDs, capabilities and pricing across providers and operators.

GET/v1/models/count

Count catalog models by output modality.

Parameters (1)
  • output_modalitiesstring (query)

    Comma-separated list of text, image, audio, embeddings, or all. Defaults to text.

400 Unknown modality (invalid_output_modalities).

GET/v1/providers

List providers that serve catalog models, with their data centres and policies.

GET/v1/byok

List encrypted bring-your-own-key provider credentials.

POST/v1/byok

Create an encrypted bring-your-own-key provider credential.

GET/v1/byok/00000000-0000-4000-8000-000000000000

Get a bring-your-own-key provider credential by ID.

GET/v1/workspaces

List enterprise workspaces for the management key.

POST/v1/workspaces

Create an enterprise workspace.

GET/v1/workspaces/default

Get a workspace by ID or slug.

GET/v1/organization/members

List organization members available to workspaces.

GET/v1/observability/destinations

List workspace-scoped observability destinations.

POST/v1/observability/destinations

Create an encrypted observability destination.

GET/v1/observability/destinations/00000000-0000-4000-8000-000000000000

Get an observability destination by ID.

POST/v1/presets/default/chat/completions

Create or version a reusable chat-completions preset.

POST/v1/embeddings

Generate text embeddings.

POST/v1/rerank

Rerank documents against a query.

POST/v1/images/generations

Generate images from text prompts.

POST/v1/images/edits

Edit or inpaint images with a prompt (multipart/form-data).

POST/v1/audio/speech

Generate speech from text (TTS).

POST/v1/batch

Submit a batch of requests for parallel processing.

GET/v1/batch

Retrieve a caller-scoped batch with the required ?id= query parameter.

GET/v1/operators

List active operators on the network.