Atomesus API

Quickstart

1. Create an API key in the console (Developer → API Keys). Copy the secret immediately — it is shown once.
2. Set ATOMESUS_API_KEY=atms_sk_YOUR_KEY_HERE in your environment (never commit real keys).
3. Call list models or chat completions (examples below).

curl https://api.atomesus.com/v1/models \
  -H "Authorization: Bearer $ATOMESUS_API_KEY"

Authentication

All /v1/* routes require an API key via either header:

• Authorization: Bearer atms_sk_...
• X-API-Key: atms_sk_...

Keys use prefix atms_sk_ and length ≥ 20. JWT is only for console key management (POST/GET/DELETE /api/gateway/keys), not for /v1/*.

Endpoints

Request — chat completions

{
  "model": "cipher",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ]
}

Response — non-streaming

1{
2  "id": "chatcmpl-...",
3  "object": "chat.completion",
4  "created": 1716900000,
5  "model": "cipher",
6  "choices": [{
7    "index": 0,
8    "message": { "role": "assistant", "content": "..." },
9    "finish_reason": "stop"
10  }],
11  "usage": {
12    "prompt_tokens": 10,
13    "completion_tokens": 20,
14    "total_tokens": 30
15  },
16  "system_fingerprint": "atms-fp-1"
17}

Primary model id: cipher. Assistant text: choices[0].message.content

Code examples

curl https://api.atomesus.com/v1/models \
  -H "Authorization: Bearer $ATOMESUS_API_KEY"

curl https://api.atomesus.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ATOMESUS_API_KEY" \
  -d '{"model":"cipher","messages":[{"role":"user","content":"Hello!"}]}' \
  -i

curl https://api.atomesus.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ATOMESUS_API_KEY" \
  -d '{"model":"cipher","messages":[{"role":"user","content":"Hello!"}],"stream":true}' \
  -N

1# After chat request, inspect headers from -i output:
2# X-Credit-Balance-INR, X-Request-Cost-INR, X-Tokens-Input, X-Tokens-Output
3
4curl -s https://api.atomesus.com/v1/chat/completions \
5  -H "Content-Type: application/json" \
6  -H "Authorization: Bearer $ATOMESUS_API_KEY" \
7  -d '{"model":"cipher","messages":[{"role":"user","content":"Hello!"}]}' \
8  -D headers.txt -o body.json
9
10grep -i x-credit-balance-inr headers.txt
11cat body.json

1# 401 invalid_api_key / 402 insufficient_credits
2curl -s https://api.atomesus.com/v1/chat/completions \
3  -H "Content-Type: application/json" \
4  -H "Authorization: Bearer $ATOMESUS_API_KEY" \
5  -w "\nHTTP %{http_code}\n" \
6  -d '{"model":"cipher","messages":[{"role":"user","content":"Hi"}]}'
7
8# Parse JSON error:
9# {"error":{"message":"...","type":"authentication_error","code":"invalid_api_key"}}

Streaming

Add "stream": true to the chat body. Responses use Server-Sent Events: lines prefixed with data: containing JSON chunks, ending with data: [DONE].

Parse each chunk's choices[0].delta.content for incremental text. Billing headers are available when the stream completes.

Billing

Errors

1{
2  "error": {
3    "message": "Invalid API key or key has been revoked.",
4    "type": "authentication_error",
5    "code": "invalid_api_key"
6  }
7}

402 responses may include top_up_url:

Pricing

Security

• Store keys in environment variables, not source control.
• Never log full API keys in production.
• Rotate and revoke compromised keys in the API Keys console.
• Use separate keys per environment (dev/staging/prod).

FAQ

Why are my system messages ignored?

Atomesus manages identity and behavior at the gateway level to ensure consistent, safe responses across all API users. Client-side system role messages are not forwarded to the model..

Which model id should I use?

Use "cipher" — it is the primary branded model in all responses.

How do I read usage for streaming?

Token counts and X-Credit-* headers are available on the final response headers when the stream completes. Parse SSE chunks for content deltas.

Where do I create API keys?

In the app: Sidebar → Developer, or Profile → API Keys. The full secret is shown once at creation.