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

# API Reference

> Complete reference for the Foil REST API

# API Reference

The Foil API provides programmatic access to traces, alerts, analytics, and more.

## Base URL

```
https://api.getfoil.ai/api
```

For self-hosted deployments, use your instance URL.

## Authentication

Foil supports two authentication methods:

### JWT Bearer Token

For dashboard and user-authenticated requests:

```bash theme={null}
curl -X GET https://api.getfoil.ai/api/users/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Obtain a JWT token via the login endpoint:

```bash theme={null}
POST /api/auth/login
{
  "email": "user@example.com",
  "password": "your-password"
}
```

### API Key

For SDK and programmatic access:

```bash theme={null}
curl -X POST https://api.getfoil.ai/api/signals \
  -H "x-api-key: sk_live_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{"signalName": "user_rating", "value": 5}'
```

API keys are created in the dashboard under **Settings > API Keys**.

<Warning>
  API keys provide full access to your data. Keep them secure and never expose them in client-side code.
</Warning>

## Rate Limits

| Tier      | Limit       | Endpoints                        |
| --------- | ----------- | -------------------------------- |
| Standard  | 100 req/min | Users, Analytics, Agents, Events |
| Strict    | 20 req/min  | API Keys, Admin                  |
| Ingestion | 500 req/min | Spans, Signals, Logs             |

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
```

## Response Format

All responses are JSON with consistent structure:

### Success Response

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Description of what went wrong",
    "code": "ERROR_CODE"
  }
}
```

## Common Error Codes

| Code               | HTTP Status | Description                       |
| ------------------ | ----------- | --------------------------------- |
| `UNAUTHORIZED`     | 401         | Missing or invalid authentication |
| `FORBIDDEN`        | 403         | Insufficient permissions          |
| `NOT_FOUND`        | 404         | Resource doesn't exist            |
| `VALIDATION_ERROR` | 400         | Invalid request parameters        |
| `RATE_LIMITED`     | 429         | Too many requests                 |
| `INTERNAL_ERROR`   | 500         | Server error                      |

## Pagination

List endpoints support pagination:

```bash theme={null}
GET /api/spans/traces?limit=50&skip=100
```

| Parameter | Default | Description                        |
| --------- | ------- | ---------------------------------- |
| `limit`   | 50      | Number of items per page (max 100) |
| `skip`    | 0       | Number of items to skip            |

Response includes pagination info:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "skip": 100,
    "hasMore": true
  }
}
```

## Date Filtering

Most endpoints accept date filters:

```bash theme={null}
GET /api/analytics/metrics?startDate=2024-01-01&endDate=2024-01-31
```

Dates should be in ISO 8601 format: `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ssZ`

## Core Endpoints

### Users

| Method | Endpoint         | Description                                            |
| ------ | ---------------- | ------------------------------------------------------ |
| GET    | `/users/profile` | Get user profile with subscription and resource counts |

### Authentication

| Method | Endpoint                | Description               |
| ------ | ----------------------- | ------------------------- |
| POST   | `/auth/login`           | User login                |
| POST   | `/auth/register`        | User registration         |
| POST   | `/auth/forgot-password` | Request password reset    |
| POST   | `/auth/reset-password`  | Reset password with token |
| GET    | `/auth/verify-email`    | Verify email address      |

### API Keys

| Method | Endpoint            | Description        |
| ------ | ------------------- | ------------------ |
| POST   | `/keys`             | Create new API key |
| GET    | `/keys`             | List all API keys  |
| PUT    | `/keys/:id/refresh` | Rotate API key     |
| POST   | `/keys/:id/revoke`  | Revoke API key     |
| DELETE | `/keys/:id`         | Delete API key     |

### Spans & Traces

| Method | Endpoint                 | Description                  |
| ------ | ------------------------ | ---------------------------- |
| GET    | `/spans/traces`          | List traces (root spans)     |
| GET    | `/spans/traces/:traceId` | Get trace with all spans     |
| GET    | `/spans/filters`         | Get available filter options |

### Signals

| Method | Endpoint                  | Description             |
| ------ | ------------------------- | ----------------------- |
| POST   | `/signals`                | Record a signal         |
| POST   | `/signals/batch`          | Record multiple signals |
| GET    | `/signals`                | List signals            |
| GET    | `/signals/summary`        | Get signal aggregations |
| GET    | `/signals/trace/:traceId` | Get signals for trace   |

### Agents

| Method | Endpoint                  | Description           |
| ------ | ------------------------- | --------------------- |
| GET    | `/agents`                 | List all agents       |
| POST   | `/agents`                 | Create agent          |
| GET    | `/agents/:agentId`        | Get agent             |
| PUT    | `/agents/:agentId`        | Update agent          |
| DELETE | `/agents/:agentId`        | Delete agent          |
| PUT    | `/agents/:agentId/alerts` | Update alert settings |

### Alerts

| Method | Endpoint                             | Description            |
| ------ | ------------------------------------ | ---------------------- |
| GET    | `/spans/alerts`                      | List all alerts        |
| GET    | `/spans/alerts/summary`              | Alert summary by agent |
| GET    | `/spans/alerts/:alertId`             | Get alert details      |
| PUT    | `/spans/alerts/:alertId/acknowledge` | Acknowledge alert      |
| PUT    | `/spans/alerts/:alertId/reopen`      | Reopen alert           |

### Analytics

| Method | Endpoint                                | Description           |
| ------ | --------------------------------------- | --------------------- |
| GET    | `/analytics/metrics`                    | Dashboard metrics     |
| GET    | `/analytics/traces/success-failure`     | Success/failure rates |
| GET    | `/analytics/traces/requests-over-time`  | Request volume        |
| GET    | `/analytics/traces/latency-percentiles` | Latency metrics       |
| GET    | `/analytics/traces/token-usage`         | Token consumption     |
| GET    | `/analytics/costs`                      | Cost breakdown        |

### Experiments

| Method | Endpoint                   | Description            |
| ------ | -------------------------- | ---------------------- |
| GET    | `/experiments`             | List experiments       |
| POST   | `/experiments`             | Create experiment      |
| GET    | `/experiments/:id`         | Get experiment         |
| POST   | `/experiments/:id/start`   | Start experiment       |
| POST   | `/experiments/:id/pause`   | Pause experiment       |
| POST   | `/experiments/:id/stop`    | Stop experiment        |
| GET    | `/experiments/:id/assign`  | Get variant assignment |
| GET    | `/experiments/:id/results` | Get experiment results |

## SDKs

For easier integration, use our official SDKs:

<CardGroup cols={2}>
  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript/index">
    npm install @getfoil/foil-js
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python/index">
    pip install foil-sdk
  </Card>
</CardGroup>