API Reference

The Attenval API is an OpenAI-compatible interface at https://api.attenval.com/v1.

Authentication

All authenticated requests must include an Authorization header containing your API key:

Authorization: Bearer atv_live_YOUR_KEY

1. Chat Completions

`POST /v1/chat/completions`

Generates model responses for conversation turns. This endpoint is streaming-only: the Worker always dispatches stream: true and returns Server-Sent Events (text/event-stream). A non-stream JSON completion body is not available.

Request Headers

Header	Type	Description
`Authorization`	`string`	`Bearer atv_live_YOUR_KEY`
`Content-Type`	`string`	`application/json`

Request Body

Field	Type	Required	Description
`model`	`string`	Yes	Alias: `attenval-auto`, `attenval-fast`, `attenval-code`, or `attenval-smart`.
`messages`	`array`	Yes	List of message objects with `role` and `content`.
`temperature`	`number`	No	Sampling temperature (0.0 to 2.0). Defaults to `0.7`.
`max_tokens`	`integer`	No	Maximum tokens to generate in response.
`stream`	`boolean`	No	Accepted for client compatibility. Always treated as `true`; the response is SSE.
`top_p`	`number`	No	Nucleus sampling probability cutoff. Defaults to `1.0`.

Example Request

{
  "model": "attenval-smart",
  "messages": [
    { "role": "system", "content": "You are a senior systems architect." },
    { "role": "user", "content": "Summarize how Attenval aliases work." }
  ],
  "max_tokens": 500,
  "temperature": 0.3,
  "stream": true
}

Example Response (SSE)

data: {"id":"chatcmpl-atv-583921","object":"chat.completion.chunk","created":1786845700,"model":"attenval-smart","choices":[{"index":0,"delta":{"role":"assistant","content":"Use a stable alias"},"finish_reason":null}]}

data: {"id":"chatcmpl-atv-583921","object":"chat.completion.chunk","created":1786845700,"model":"attenval-smart","choices":[{"index":0,"delta":{"content":" that matches the work."},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-atv-583921","object":"chat.completion.chunk","created":1786845700,"model":"attenval-smart","choices":[],"attenval":{"requested_model":"attenval-smart","credits_used":60,"balance_remaining":145872}}

data: [DONE]

The attenval object contains only requested_model, credits_used, and balance_remaining. The amount a request uses depends on the alias. Each model field is the public alias.

2. Models

`GET /v1/models`

Lists the aliases currently available to the API.

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "attenval-auto",
      "object": "model",
      "created": 1723766400,
      "owned_by": "attenval"
    },
    {
      "id": "attenval-fast",
      "object": "model",
      "created": 1723766400,
      "owned_by": "attenval"
    },
    {
      "id": "attenval-code",
      "object": "model",
      "created": 1723766400,
      "owned_by": "attenval"
    },
    {
      "id": "attenval-smart",
      "object": "model",
      "created": 1723766400,
      "owned_by": "attenval"
    }
  ]
}

Each item is { id, object, created, owned_by }. Public names: Auto, Fast, Code, Smart.

3. Credits

`GET /v1/credits`

Returns the authenticated account’s earned-credit balance.

Example Response

{
  "earned_available": 15000,
  "earned_expires_at": "2026-09-16T12:00:00Z",
  "purchased_available": 0,
  "total_available": 15000
}

Credits are earned promotional units. Watch a verified spotlight in the app to earn 5,000 credits (up to 5 per day). Earned credits have a 30-day rolling expiry.

4. Usage

`GET /v1/usage`

Returns usage totals for the authenticated account, plus a recent daily breakdown.

Example Response

{
  "account_pid": "acc_8f93a2e1",
  "total_tokens": 996600,
  "credits_spent": 28450,
  "requests_count": 1420,
  "daily": [
    {
      "day_bucket": "2026-08-16",
      "total_tokens": 42100,
      "credits_spent": 980,
      "requests_count": 54
    }
  ]
}

5. API keys

`GET /v1/api-keys`

Returns keys for the authenticated account. Secrets are not included.

`POST /v1/api-keys`

Creates a new API key. The secret is returned once.

{
  "name": "Production CLI Bot",
  "environment": "live",
  "daily_cap_credits": 50000
}

The response includes key in the form atv_live_YOUR_KEY (or atv_test_... for test keys) only on create.

`DELETE /v1/api-keys/:id`

Revokes the specified key. Later requests with that key return HTTP 401 Unauthorized.