---
title: "Inference API access | Tarka Docs"
description: "Choose a Tarka inference endpoint, authenticate public requests, discover models, and handle API errors."
url: "https://tarkahq.com/docs/inference/api-access/"
---

Available Inference · 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 management **Use 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](https://tarkahq.com/console) [Control API reference](https://tarkahq.com/docs/control-api/)

Network surfaces

## One service, three transports

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

Public `https://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 Host `http://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`

gRPC `grpc.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 API `bearer token`

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

Agent Host `no bearer token`

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

### OpenAI SDK inside an Agent Host

Python `host-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 response `200 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.

Example `403 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.