Use the API

The API follows the OpenAI chat completions shape. Most clients only need a new base URL and a key.

Create a key

Sign in to the portal at https://platform.katara.com and open API Keys. Create an organization if you do not have one and select an environment: Test while you build, Live for real traffic. Enable the Cortex inference permission, choose a name, an expiry date and a payment method, then create the key. Copy it immediately; its secret is shown once.

The environment decides where the key’s requests are served and paid. A Live key pays from Account Credits or in USDC on Avalanche C-Chain from your wallet. Credits need no wallet: a new account starts with a signup credit, and you can buy more by card under Billing. A Test key pays in test USDC on Avalanche Fuji, from your wallet; Account Credits do not pay for Test model calls. Networks compares the two.

A key belongs to one organization and one environment. The same key can carry explicit Synapse and Locus permissions. Choosing those permissions does not grant spending authority or bypass approvals. An agent’s paid model calls in Test are Test Compute: they are paid by the run’s budget, in Account Credits or in test USDC, under the run’s consent and limits, whatever the key pays with.

Revoked and expired keys are refused on subsequent requests. Issue a replacement with the required scopes and expiry to rotate a key. When 80% of a key’s lifetime has passed, Katara reminds the person who created it, unless they have already created a key with the same name in the same environment that lasts longer. Wallet payment methods still require the wallet’s spending approval; a key with no inference permission needs no wallet.

A key’s prefix names its environment: keys from a Live environment start with kat_live_, keys from a Test environment with kat_test_. Keys created before the prefixes followed the environment keep the prefix they were issued with and keep working in the environment they belong to.

Send a request

curl https://api.katara.com/v1/chat/completions \
  -H "Authorization: Bearer $KATARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "katara/cortex@1",
    "messages": [{"role": "user", "content": "Explain a Merkle tree in two sentences."}],
    "max_tokens": 200
  }'

katara/cortex@1 picks a model for the request and keeps answering when a provider goes away; name a specific model instead when you need exactly that one. The reply carries a katara object with the charge and who served it. A key that pays with credits sees the charge in Credits, under the legacy field name cost_usd:

"katara": { "billing_method": "credits", "cost_usd": "0.000018", "served": { "model": "katara/deepseek-chat@1" } }

A key that pays with USDC sees the settled price in USDC and the provider’s address: "cost_usdc": "0.000018", "provider": "0xfFe5…38DC". Usage and costs lists every field.

Send it with a Test key and the same request runs on Avalanche Fuji; the address does not change.

With the OpenAI client

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.katara.com/v1", api_key=os.environ["KATARA_API_KEY"])
reply = client.chat.completions.create(
    model="katara/cortex@1",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)

Streaming works the same way with stream=True. The final chunk before [DONE] has an empty choices array and carries the katara charge.

Tool calling follows the OpenAI shape too; see Tool calling for what each model is certified for.

client.responses.create(model=..., input=..., store=False) works with the same key. Katara keeps no responses, so send the whole conversation each time: storing, previous_response_id and conversations are refused. The Responses API lists what it takes.

List models

GET /v1/models needs no key and returns every model with its capabilities, context window, and the lowest live price. See the API reference for the full shapes and the error codes.