API Reference

The Attenval API is served globally via Cloudflare edge infrastructure at https://api.attenval.com/v1.

Authentication

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

Authorization: Bearer atv_live_xxxxxxxxxxxxxxxxxxxxxxxx

1. Chat Completions

`POST /v1/chat/completions`

Generates model responses for conversation turns. Supports both non-streaming and Server-Sent Events (SSE) streaming.

Request Headers

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

Request Body

Field	Type	Required	Description
`model`	`string`	Yes	Model alias (`attenval-auto`, `attenval-fast`, `attenval-code`, `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	If `true`, returns SSE chunks. Defaults to `false`.
`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": "Compare SQLite Durable Objects with traditional Redis clusters for ledger consistency." }
  ],
  "max_tokens": 500,
  "temperature": 0.3
}

Example Response

{
  "id": "chatcmpl-atv-583921",
  "object": "chat.completion",
  "created": 1786845700,
  "model": "attenval-smart",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Durable Objects provide strong single-point-of-coordination consistency backed by local SQLite storage..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 198,
    "total_tokens": 240
  },
  "attenval": {
    "requested_model": "attenval-smart",
    "routed_model": "deepseek-ai/deepseek-r1",
    "credits_used": 60,
    "balance_remaining": 145872,
    "latency_ms": 612
  }
}

2. Model Catalog

`GET /v1/models`

Lists all model aliases currently available for routing, along with their context limits and integer credit pricing per 1,000 tokens.

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "attenval-auto",
      "object": "model",
      "name": "Attenval Auto (Intelligent Routing)",
      "context_window": 128000,
      "pricing": {
        "input_credits_per_1k": 10,
        "output_credits_per_1k": 30
      },
      "description": "Optimizes cost and intelligence automatically based on prompt complexity."
    },
    {
      "id": "attenval-fast",
      "object": "model",
      "name": "Attenval Fast (Low Latency)",
      "context_window": 64000,
      "pricing": {
        "input_credits_per_1k": 4,
        "output_credits_per_1k": 12
      },
      "description": "Sub-200ms latency for autocomplete, classification, and summarization."
    },
    {
      "id": "attenval-code",
      "object": "model",
      "name": "Attenval Code (Technical & Refactoring)",
      "context_window": 128000,
      "pricing": {
        "input_credits_per_1k": 12,
        "output_credits_per_1k": 40
      },
      "description": "High-accuracy code generation, debugging, and multi-file reasoning."
    },
    {
      "id": "attenval-smart",
      "object": "model",
      "name": "Attenval Smart (Deep Reasoning & Synthesis)",
      "context_window": 128000,
      "pricing": {
        "input_credits_per_1k": 25,
        "output_credits_per_1k": 75
      },
      "description": "Complex reasoning, math, and multi-step agentic planning."
    }
  ]
}

3. Wallet & Balance

`GET /v1/credits`

Returns the current active credit balances, separating promotional earned credits from persistent purchased credits.

Example Response

{
  "account_id": "acc_8f93a2e1",
  "total_credits": 145950,
  "earned_credits": {
    "balance": 18450,
    "expires_at": "2026-09-27T12:00:00Z",
    "days_remaining": 42
  },
  "purchased_credits": {
    "balance": 127500,
    "expires_at": null
  },
  "currency": "ATTENVAL_CREDITS"
}

4. Usage Rollups

`GET /v1/usage`

Retrieves historical usage events aggregated by day and model alias.

Query Parameters

start_date (ISO date, e.g. 2026-08-01)
end_date (ISO date, e.g. 2026-08-16)
model (optional filter)

Example Response

{
  "period_start": "2026-08-01T00:00:00Z",
  "period_end": "2026-08-16T23:59:59Z",
  "total_requests": 1420,
  "total_prompt_tokens": 312400,
  "total_completion_tokens": 684200,
  "total_credits_spent": 28450,
  "breakdown_by_model": {
    "attenval-auto": { "requests": 820, "credits": 14500 },
    "attenval-code": { "requests": 410, "credits": 9800 },
    "attenval-fast": { "requests": 190, "credits": 4150 }
  }
}

5. API Keys Management

`GET /v1/api-keys`

Returns all active keys for the authenticated account (secrets redacted).

`POST /v1/api-keys`

Creates a new API key with optional name, environment (live or test), and daily credit cap.

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

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

Immediately revokes the specified API key. Any subsequent request using this key will return HTTP 401 Unauthorized.