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, or with the Test environment’s test credits, 5 a day with no value; 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",
    "messages": [{"role": "user", "content": "Explain a Merkle tree in two sentences."}],
    "max_tokens": 200
  }'

Katara Cortex picks a model for the request and keeps answering when a provider goes away. A client that sends its own default model name needs no change (Model names in requests). The reply carries a katara object with the charge. A key that pays with credits sees it in Credits, under the legacy field name cost_usd:

"katara": { "billing_method": "credits", "cost_usd": "0.000018" }

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",
    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, and Katara can search the web for the model; see Tool calling.

client.responses.create(model=..., input=...) works with the same key. Responses are stored for 30 days unless you send store=False, so previous_response_id continues a conversation. Responses lists what it takes.

Other clients

The same key works in the clients that speak these formats:

• Anthropic SDKs and Claude Code: base URL https://api.katara.com (no /v1). For Claude Code, set ANTHROPIC_BASE_URL=https://api.katara.com and put the key in ANTHROPIC_API_KEY. See Messages.
• OpenAI SDKs, LiteLLM, LangChain and the Vercel AI SDK: base URL https://api.katara.com/v1, with any model name.
• Cursor: turn on the custom OpenAI base URL in its model settings, enter https://api.katara.com/v1, and use the key as the OpenAI API key.

Every model name a client sends is served by Cortex, so a client’s default model needs no change.

List models

GET /v1/models needs no key and returns katara/cortex with its capabilities, context window and price ceiling. The list also carries katara/cortex-genius and katara/cortex-smart, which only requests paid per call with x402 may name; a key that names them is refused. See the API reference for the full shapes and the error codes.