---
title: "Control API keys, policy, and usage | Tarka Docs"
description: "Discover active Tarka models, manage scoped API keys, configure organization limits, and inspect usage through the Control API."
url: "https://tarkahq.com/docs/control-api/keys-policy-usage/"
---

Available Control API · Inference management

# Models, keys, limits, usage, and resource state

Manage the credentials and organization policy used by the runtime APIs, then inspect the metering and reconciliation state they produce.

Catalog

## Discover active aliases before creating policy

`GET /models` returns active catalog metadata, pricing inputs, context window, backend, provider, upstream model, modality, and capabilities. Add `?modality=chat`, `ocr`, `layout`, `stt`, `tts`, `embedding`, or `rerank` for an exact filter.

Model catalog `account token`

```
curl "https://tarka.rest/control/v1/models?modality=chat" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"
```

**Control discovery and runtime discovery answer different questions.**

`GET /control/v1/models` lists the active management catalog and each model's `access_product`. `GET /v1/models` uses a `tk_live_` key and returns only aliases allowed by both the key scope and the key creator's current product entitlement.

Credentials

## Issue narrowly scoped `tk_live_` keys

Owners, admins, and operators may create and revoke keys. Model access is grouped into `himalaya` (HimalayaAI models), `inference` (other LLMs), and `utilities` (OCR and speech). `sandboxes` grants code-sandbox access. An empty scope list preserves the historical `inference` default.

Create key `POST`

```
curl -X POST "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/api-keys" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label":"production inference",
    "scopes":["himalaya"]
  }'
```

One-time secret `200 OK`

```
{
  "api_key": {
    "id": "6e0a...",
    "org_id": "9df4...",
    "label": "production inference",
    "key_prefix": "tk_live_91a3",
    "status": "active",
    "allowed_model_aliases": [],
    "scopes": ["himalaya"],
    "created_at": "2026-08-30T14:00:00Z"
  },
  "plaintext_key": "tk_live_returned_once"
}
```

**`plaintext_key` is returned once.**

Write it directly to a secret manager. List responses contain only `key_prefix`, status, scope, model policy, dates, and revocation metadata. Lost secrets cannot be recovered.

**Label** `1–80 characters`

Operator-readable metadata; never put a secret in it.

**Scopes** `approved products only`

The server refuses scopes the key creator is not currently approved to use.

**Allowed aliases** `optional override`

Every named alias must exist and be active. Runtime policy intersects the key override with organization policy.

Product approval is evaluated again on every request. Suspending or removing an entitlement immediately blocks existing keys for that product. Key revocation remains permanent and idempotent.

Spend limits

## Cap monthly spend in money

`GET` returns the organization's monthly limit, a limit for each product that has one, and what each has been charged since the start of the UTC calendar month. `PUT` replaces every limit and requires owner or admin.

Replace spend limits `PUT /spend-limits`

```
curl -X PUT "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/spend-limits" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency":"usd",
    "monthly_limit_microcents":"10000000000",
    "product_limits":[
      {"product":"inference","monthly_limit_microcents":"6000000000"}
    ]
  }'
```

Limits and spend `200 OK`

```
{
  "org_id": "9df4...",
  "currency": "usd",
  "monthly_limit_microcents": "10000000000",
  "spent_microcents": "6180000000",
  "products": [
    {"product": "inference", "metered": true,
     "monthly_limit_microcents": "6000000000", "spent_microcents": "5412000000"},
    {"product": "utilities", "metered": true, "spent_microcents": "768000000"},
    {"product": "sandboxes", "metered": false, "spent_microcents": "0"}
  ],
  "period_start": "2026-10-01T00:00:00Z",
  "period_end": "2026-11-01T00:00:00Z",
  "as_of": "2026-10-13T16:00:00Z"
}
```

**Money, not tokens** `currency microcents`

Amounts are in the organization's billing currency, returned as `currency`. Send that currency back with every update.

**Product limits sit inside** `optional`

A product without its own limit draws on the monthly limit. Product limits do not have to add up to it. Only products with `metered:true` take one.

**At a limit** `HTTP 402`

The Inference API refuses a priced request that could take spend past a limit with `spend_limit_reached`, before it reaches the model. Free models are never stopped. A limit of `0` stops all priced use it covers.

Limits

## Replace the effective inference quota policy

`GET` returns an allow-all default when no row exists. `PUT` replaces optional concurrency, request, token, and model restrictions and requires owner or admin. For limits in money, use spend limits above.

Replace policy `PUT /quota-policy`

```
curl -X PUT "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/quota-policy" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "max_concurrent_requests":8,
    "monthly_request_budget":"100000",
    "monthly_token_budget":"50000000",
    "allow_all_models":false,
    "allowed_model_aliases":["himalaya-q8"]
  }'
```

**Optional numeric limits**

Omit or send `null` for no explicit organization override. Values must be non-negative.

**Allow every model**

Set `allow_all_models:true`; the alias list is ignored for policy storage.

**Restrict models**

Set `allow_all_models:false` and provide at least one active alias.

Metering

## Inspect events and the current UTC month

`ListUsageEvents` returns newest requests first with request ID, public model alias, provider routing, token counts, status, latency, request type, error code, cost in microcents, and creation time. `limit` defaults to 25 and caps at 100.

`GetUsageSummary` returns a half-open UTC interval `[period_start, period_end)` for the current calendar month with request count, token totals, total microcent cost, error count, and average latency.

**Microcents are integer accounting units.**

One USD cent is 1,000,000 microcents. Keep values as integers through billing calculations and format them only for display.

Shared state

## Read reconciled resource state

Generic resource reads cover `inference_service`, `agent`, `job`, `sandbox`, `bucket`, and `git_repo`. Filter lists with `?resource_type=...`. Each result includes desired `spec`, lifecycle `status`, `status_detail`, namespace, external URL, and timestamps.

**Generic reads are not generic lifecycle mutations.**

Use the product-specific create, apply, delete, revoke, or execute method documented for that resource. There is no catch-all resource delete endpoint.

Reference

## REST routes

Prefix every path with `https://tarka.rest/control/v1`.

| Method | Path | Ability |
| --- | --- | --- |
| `GET` | `/models` | List active models; optional modality filter |
| `POST` | `/orgs/{org_id}/api-keys` | Create scoped key and return plaintext once |
| `GET` | `/orgs/{org_id}/api-keys` | List redacted key metadata |
| `POST` | `/orgs/{org_id}/api-keys/{api_key_id}:revoke` | Permanently revoke a key |
| `GET` | `/orgs/{org_id}/quota-policy` | Read effective inference policy |
| `PUT` | `/orgs/{org_id}/quota-policy` | Replace inference policy |
| `GET` | `/orgs/{org_id}/spend-limits` | Read monthly spend limits and spend this month |
| `PUT` | `/orgs/{org_id}/spend-limits` | Replace monthly spend limits |
| `GET` | `/orgs/{org_id}/usage/events` | List newest usage events |
| `GET` | `/orgs/{org_id}/usage/summary` | Aggregate the current UTC month |
| `GET` | `/orgs/{org_id}/resources` | List provisioned resource state |
| `GET` | `/orgs/{org_id}/resources/{resource_id}` | Read one resource |