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

# API Overview

> Understand Thunder API conventions, base URL, and error handling

## Base URL

All API requests should be made to:

```
https://api.usethunder.com/v1/
```

## Authentication

All endpoints require authentication via the `x-api-key` header. See [Authentication](/authentication) for details.

## Request Format

* **Content-Type**: `application/json` for POST requests
* **Accept**: `application/json`

## Response Format

All responses are JSON objects. Successful responses return the requested data directly. Error responses follow a standard format:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}
```

## Error Codes

| Code               | HTTP Status | Description                         |
| ------------------ | ----------- | ----------------------------------- |
| `VALIDATION_ERROR` | 400         | Request validation failed           |
| `BAD_REQUEST`      | 400         | Malformed request                   |
| `UNAUTHORIZED`     | 401         | Authentication required             |
| `MISSING_API_KEY`  | 401         | No API key provided                 |
| `INVALID_API_KEY`  | 401         | API key is invalid or inactive      |
| `FORBIDDEN`        | 403         | Access denied                       |
| `NOT_FOUND`        | 404         | Resource not found                  |
| `CONFLICT`         | 409         | Resource conflict (e.g., duplicate) |
| `INTERNAL_ERROR`   | 500         | Internal server error               |

## Validation Errors

When request validation fails, the `details` field contains an array of specific field errors:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "path": "messages.0.content",
        "message": "Content must not be empty"
      },
      {
        "path": "instanceId",
        "message": "Invalid uuid"
      }
    ]
  }
}
```

## Rate Limits

| Limit               | Value |
| ------------------- | ----- |
| Requests per second | 1,000 |

Rate limit headers are included in responses:

* `X-RateLimit-Limit` - Maximum requests allowed
* `X-RateLimit-Remaining` - Requests remaining in current window
* `X-RateLimit-Reset` - Unix timestamp when the limit resets

When rate limited, you'll receive a `429 Too Many Requests` response.

## Pagination

The query endpoint supports pagination via `limit` and `offset` parameters:

| Parameter | Type    | Default | Description                    |
| --------- | ------- | ------- | ------------------------------ |
| `limit`   | integer | 50      | Max results per page (1-10000) |
| `offset`  | integer | 0       | Number of results to skip      |

Paginated responses include a `pagination` object:

```json theme={null}
{
  "elements": [...],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}
```

## Instance Scoping

All analytics in Thunder are scoped to instances. When you query metrics, you must specify an `instanceId` and results will only include data from that instance. Topics, signals, gaps, and usage metrics are analyzed separately per instance.

## Available Endpoints

<CardGroup cols={2}>
  <Card title="POST /ingest" icon="upload" href="/api-reference/ingest/post-ingest">
    Ingest conversation messages
  </Card>

  <Card title="GET /query" icon="chart-bar" href="/api-reference/query/get-query">
    Query analytics and metrics
  </Card>
</CardGroup>