AvailableInference · API access

Endpoints and authentication

Use public HTTPS, keyless host-local REST, or native gRPC. Every transport reaches the same policy-enforced inference service.

Provisioning and managementUse the console or the Control API.

Create, revoke, and scope public API keys in the console or through the Control API. Model access and organization limits are reflected on both management surfaces.

Open console Control API reference

Network surfaces

One service, three transports

Model aliases, authorization, limits, routing, and usage accounting are shared. Reachability and wire format differ.

Publichttps://tarka.rest/v1

Internet-facing and authenticated

Use from your backend, CI system, or development machine. HTTPS and an API key with the inference scope are required.

Authorization: Bearer tk_live_...

Agent Hosthttp://tarka/v1

Host-local and keyless

Reachable only inside a Tarka Agent Host. Requests are authorized automatically for that host and its selected model set.

No caller credential

gRPCgrpc.tarka.rest:443

Typed and authenticated

Use generated protobuf clients over TLS. Send the same public key as authorization: Bearer ... metadata.

tarka.inference.v2.InferenceService

Keep public keys server-side.

Never embed a tk_live_... key in browser code. http://tarka is not a public fallback and should not resolve outside a Tarka Agent Host.

/v2 is deprecated.

Existing REST integrations may temporarily use https://tarka.rest/v2, but new code must use /v1. The v2 in the protobuf package name is retained for gRPC wire compatibility and does not make the REST alias newer.

Examples

Authenticate the surface you use

Public APIbearer token

curl "https://tarka.rest/v1/models" \
  -H "Authorization: Bearer $TARKA_API_KEY"

Agent Hostno bearer token

curl "http://tarka/v1/models"

OpenAI SDK inside an Agent Host

Pythonhost-local compatibility marker

from openai import OpenAI

client = OpenAI(
    base_url="http://tarka/v1",
    # The SDK requires a non-empty value. Host-local requests are
    # authorized automatically; this value is not a credential.
    api_key="tarka-local",
)

models = client.models.list()

The platform owns the host identity.

Agent applications do not receive a public or host credential. Host-local requests are limited to the selected chat model and active utility aliases configured for the host.

Discovery

List models before routing traffic

GET /models returns only models deployed and allowed for the current organization. Treat it as the source of truth instead of hard-coding preview aliases.

Example response200 OK

{
  "object": "list",
  "data": [
    {
      "id": "himalaya-q8",
      "object": "model",
      "created": 1787596800,
      "owned_by": "tarka"
    }
  ]
}

Reliability

Errors and retries

JSON failures use an OpenAI-shaped error object. Limits apply equally to public and Agent Host traffic.

Example403 Forbidden

{
  "error": {
    "message": "The requested model is not enabled for this organization.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

Status	Meaning	Client action
`400`	Invalid body, parameter, or model capability	Correct the request.
`401`	Missing, malformed, or inactive public key	Check the bearer token.
`403`	Account, scope, membership, or model policy denied access	Check access in the console or Control API.
`429`	Rate, concurrency, request, or token limit reached	Honor `Retry-After` when present.
`500 / 502`	Service or upstream model failure	Retry transient failures with backoff.
`503`	Model capacity is temporarily unavailable	Retry with exponential backoff and jitter.
`504`	Queue or inference timeout	Retry or reduce request size.

Retry only transient 429, 502, 503, and 504 responses. A retried generation can produce different output.