aethexDocs

API Reference

LLM Keys

Link your own LLM provider API key. Every agent whose llm_model names a model on that provider then runs on your key, for calls and text chat alike. Agents on the platform default (aethex-default or a blank llm_model) and realtime models keep running on Aethex's key. Choose the model itself on the agent (PATCH /agents/{id}, llm_model). To run calls on your own OpenAI-compatible server instead, link it with provider custom: see Your own LLM.

Base URL
https://api.aethexai.com/api/v1
Endpoints
4
Scopes
llm_credentials:readllm_credentials:write
POST/llm-credentials

Check a provider API key and store it (encrypted).

Link LLM Key

Checks the key with the provider, then stores it encrypted at rest. The key is never returned in any response; key_hint shows its last four characters. Linking a key for a provider that already has one replaces the old key at once, so you can rotate a key with no gap. If the provider later refuses the key (revoked, out of credit, rate-limited), the call or chat turn fails: it never falls back to the Aethex key. Groq (groq:…), Cerebras (cerebras:…) and xAI (xai:…) models can be set on an agent only after you link that vendor's key. Realtime models keep running on the Aethex key. A custom endpoint also takes base_url and is checked with GET <base_url>/models; agents name it as custom:<model>, for voice calls only.

Request body

4
  • providerstringrequired

    Provider the key belongs to: openai, anthropic, openrouter, groq, cerebras, xai, or custom for your own OpenAI-compatible server.

  • api_keystringrequired

    The provider API key. Checked with the provider before it is stored; never echoed back.

  • labelstringoptional

    Optional human-readable label.

  • base_urlstringoptional

    Required for custom, refused for every other provider: your server's chat-completions root, such as https://llm.example.com/v1. Requests go to <base_url>/chat/completions. HTTPS on port 443 to a public host, with no credentials, query or fragment. See Your own LLM.

Errors

4
422Unprocessable Entity

The provider rejected the key, provider is not one of the supported values, or base_url is missing, malformed or does not resolve to a public address.

Check the key in your provider's console and that provider matches it.

409Conflict

Another key for the same provider was linked at the same moment.

Retry the request.

429Too Many Requests

Per-tenant link rate limit exceeded (5/min).

Retry after the Retry-After interval.

503Service Unavailable

The provider, or your base_url, could not be reached to check the key, or the rate limiter is offline.

Retry shortly.

GET/llm-credentials

List the keys linked to your account, newest first.

List LLM Keys

Returns active and released keys, newest first. Keys are never included; each entry shows key_hint, the key's last four characters, and base_url for a custom endpoint.

Path & Query

2
  • limitintegeroptional

    Maximum number of results (1 to 200, default 50).

  • offsetintegeroptional

    Number of results to skip (default 0).

GET/llm-credentials/:id

Get one linked key.

Get LLM Key

Returns one key's provider, label, key_hint, base_url (for a custom endpoint) and status. The key itself is never returned.

Path & Query

1
  • idstringrequired

    LLM key ID.

Errors

1
404Not Found

No key with this ID exists on your account.

Check the ID with GET /llm-credentials.

DELETE/llm-credentials/:id

Stop using a key and delete it.

Release LLM Key

Releases the key and erases it. Returns 204 whether or not the key was active. Agents on OpenAI, Anthropic or OpenRouter models go back to the Aethex key from their next call or chat turn. A Groq, Cerebras, xAI or custom key cannot be released while an agent still uses it.

Path & Query

1
  • idstringrequired

    LLM key ID.

Errors

1
409Conflict

Agents still use models that run only on your own key: Groq, Cerebras, xAI or custom:.

Change those agents' llm_model first. The error names them.