Tarka/Docs/Control API/Keys, policy, and usage

AvailableControl 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 catalogaccount 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 keyPOST

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 secret200 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.

Label1–80 characters

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

Scopesapproved products only

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

Allowed aliasesoptional 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 limitsPUT /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 spend200 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 tokenscurrency microcents

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

Product limits sit insideoptional

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 limitHTTP 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 policyPUT /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