Skip to content
Hydra

The AI API

The AI API lets you call the same models your company's chat uses from your own code: a script, a spreadsheet add-on, an internal tool, or any client that speaks the OpenAI or Anthropic API. Calls run on the model accounts your company connected (see Model accounts), under the same fair share as the chat. The last free slot on every account is always kept for the chat, so a script never crowds out your colleagues.

Today the AI API is for the owner and admins. A key works only while its owner still has one of those roles.

Create a key

  1. Open Settings → AI API keys.
  2. Type a Key name that says where it will live, for example laptop or route-report script, and choose Create key.
  3. Hydra shows the key once. It starts with hk_. Copy it now and choose I have copied it. If you lose it, revoke it and make another.

You can hold up to 20 keys. Hydra stores only a fingerprint of each key, never the key itself.

Call it

Replace https://hydra.example.com with your company's Hydra address.

curl https://hydra.example.com/api/ai/v1/chat/completions \
  -H "Authorization: Bearer hk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Reply with the word PONG"}]}'

With the official SDKs, set two variables:

# OpenAI clients and SDKs
export OPENAI_BASE_URL=https://hydra.example.com/api/ai/v1
export OPENAI_API_KEY=hk_YOUR_KEY

# Anthropic clients and SDKs (the SDK adds /v1 itself)
export ANTHROPIC_BASE_URL=https://hydra.example.com/api/ai
export ANTHROPIC_API_KEY=hk_YOUR_KEY

The key goes in Authorization: Bearer, or in x-api-key as Anthropic clients send it.

Endpoints

Endpoint Shape What it does
GET /api/ai/v1/models OpenAI The models this key may use: auto, plus the ids your company's model settings allow you.
POST /api/ai/v1/chat/completions OpenAI A chat answer from messages.
POST /api/ai/v1/messages Anthropic A chat answer from system and messages.
GET /api/ai/v1/usage JSON This key's totals for today and the last 30 days.
POST /api/ai/v1/images/generations OpenAI A picture from a prompt, one or two at a time, when your server has picture generation set up.

Use auto as the model to let Hydra pick, or an id from /models. Streaming works in both shapes ("stream": true).

What a call can and cannot do

The API answers text. A call has no tools, no files and no memory: it cannot read your Drive, touch the ERP or browse. Each call stands on its own; send the earlier turns in messages if you need a conversation.

Limit Value
Time for one call 5 minutes
Input 200,000 characters
Calls running together 2 per key, 4 per person
Requests per minute 20 per key

Over a limit, or when every account is busy, you get a 429 with a Retry-After header, instead of waiting behind people in the chat. Other answers you may see: 401 for a wrong or revoked key, 403 when the key's owner is no longer an owner or admin, 404 for an unknown model, 503 when no account can serve the call, 504 when the call ran out of time. Errors come in the shape of the endpoint you called, so the SDKs read them as usual.

Usage per key

Each key in Settings → AI API keys shows when it was last used and today's requests and tokens, with failures counted separately. GET /api/ai/v1/usage returns the same for today and the last 30 days: requests, errors, input and output tokens. API calls count toward your own usage, beside your chats, in System → Usage.

Revoke a key

Choose Revoke on the key, then Revoke now. The key stops working at once: the next call with it gets a 401. Revoke a key as soon as a laptop is lost or a script is retired. Revoking one key does not touch your others.

What is recorded

Every call is in the audit log as ai.call, with the key, the model, the time it took, the status and the token counts. The prompt and the answer are never recorded. Creating and revoking a key are recorded too.