> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fenra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Everything you need to integrate with the Fenra API

The Fenra API lets you send AI usage data for cost tracking and analytics.

## Base URL

```
https://ingest.fenra.io
```

## Authentication

All requests require an API key in the `X-Api-Key` header:

```bash theme={null}
curl -X POST 'https://ingest.fenra.io/usage/transactions' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '...'
```

Get your API key from [app.fenra.io](https://app.fenra.io) under **Settings → API Keys**.

<Card title="Authentication Guide" icon="key" href="/api-reference/authentication">
  How to get and use API keys.
</Card>

## Quick Example

```bash theme={null}
curl -X POST 'https://ingest.fenra.io/usage/transactions' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{
    "provider": "openai",
    "model": "gpt-4o",
    "usage": [{
      "type": "tokens",
      "metrics": {
        "input_tokens": 100,
        "output_tokens": 50,
        "total_tokens": 150
      }
    }],
    "context": {
      "billable_customer_id": "my-company"
    }
  }'
```

Response:

```json theme={null}
{
  "status": "queued",
  "events_queued": 1,
  "message": "1 transaction(s) queued for processing"
}
```

## Transaction Schema

| Field        | Required | Description                                                                             |
| ------------ | -------- | --------------------------------------------------------------------------------------- |
| `provider`   | Yes      | `openai`, `anthropic`, `gemini`, `bedrock`, `xai`, `deepseek`, or `custom`              |
| `model`      | Yes      | Model identifier (e.g., `gpt-4o`, `claude-3-5-sonnet-20241022`)                         |
| `model_tier` | No       | Pricing tier (e.g., `standard`, `batch`)                                                |
| `usage`      | Yes      | What resources the AI call consumed (tokens, images, audio, etc.). See [Usage](#usage). |
| `context`    | Yes      | Must include `billable_customer_id`; can include any additional fields                  |

## Context

Only `billable_customer_id` is required. Add any additional context fields you need. They will appear in your dashboard and can be used for filtering, alerts, and reports.

```json theme={null}
{
  "context": {
    "billable_customer_id": "acme-corp"
  }
}
```

<Tip>
  See the [Transactions Guide](/guides/transactions) for examples of useful context fields.
</Tip>

## Usage

The `usage` field describes what resources an AI call consumed. Different AI operations consume different resources:

* **Text generation** (GPT, Claude, etc.) consumes **tokens**
* **Image generation** (DALL-E, etc.) consumes **images**
* **Speech-to-text/TTS** (Whisper, etc.) consumes **audio seconds**

The `usage` field is an array because some AI calls consume multiple resource types. For example, a GPT-4 Vision request might consume both tokens (for text) and process images.

**Structure of a usage entry:**

```json theme={null}
{
  "type": "tokens",
  "metrics": {
    "input_tokens": 100,
    "output_tokens": 50,
    "total_tokens": 150
  }
}
```

Each entry has:

* **`type`**: The resource type (see table below)
* **`metrics`**: The measurements for that resource

### Usage Types

| Type            | Used For                         | Required Metrics                                                   |
| --------------- | -------------------------------- | ------------------------------------------------------------------ |
| `tokens`        | Text generation, chat, reasoning | `input_tokens`, `output_tokens`, `total_tokens`                    |
| `images`        | Image generation (DALL-E, etc.)  | `generated`                                                        |
| `audio_seconds` | Speech-to-text, TTS              | At least one of `input_seconds`, `output_seconds`, `total_seconds` |
| `video_seconds` | Video processing                 | `processed_seconds`                                                |
| `requests`      | Flat per-request pricing         | `count`                                                            |
| `custom`        | Custom billing models            | `units`                                                            |

### Example: Text Generation (Most Common)

```json theme={null}
{
  "usage": [{
    "type": "tokens",
    "metrics": {
      "input_tokens": 500,
      "output_tokens": 200,
      "total_tokens": 700
    }
  }]
}
```

### Example: Multimodal (Multiple Resource Types)

A request that generates both text and images:

```json theme={null}
{
  "usage": [
    {
      "type": "tokens",
      "metrics": {
        "input_tokens": 150,
        "output_tokens": 50,
        "total_tokens": 200
      }
    },
    {
      "type": "images",
      "metrics": {
        "generated": 2,
        "size_px": 1024
      }
    }
  ]
}
```

<Tip>
  Each usage type can only appear once per transaction. See the [Transactions Guide](/guides/transactions) for detailed information on each usage type and their optional metrics.
</Tip>

## Response Codes

| Code                 | Meaning                               |
| -------------------- | ------------------------------------- |
| `202 Accepted`       | Transaction(s) queued successfully    |
| `207 Multi-Status`   | Some transactions queued, some failed |
| `400 Bad Request`    | Validation error                      |
| `401 Unauthorized`   | Invalid API key                       |
| `500 Internal Error` | Server error (retryable)              |

<Card title="Error Reference" icon="triangle-exclamation" href="/api-reference/errors">
  Complete list of error codes and how to handle them.
</Card>

## Endpoints

<Card title="POST /usage/transactions" icon="arrow-up" href="/api-reference/endpoint/create">
  Send one or more AI usage transactions.
</Card>