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

# API Reference

> Trainly REST API for trace ingestion, scoring, analytics, testing, and version management.

## Base URL

```
https://api.trainlyai.com
```

All endpoints are scoped to a project:

```
https://api.trainlyai.com/v1/{project_id}/...
```

## Authentication

Include your API key in the `Authorization` header. Keys are prefixed with `tk_`.

```
Authorization: Bearer tk_your_api_key
```

## Rate Limiting

All endpoints are rate-limited to **100 requests per second** per API key. Exceeding this limit returns a `429` response with a `Retry-After` header.

## Response Format

All responses return JSON with `Content-Type: application/json`.

## Error Codes

| Code  | Description                                            |
| ----- | ------------------------------------------------------ |
| `400` | Bad Request — invalid or missing parameters            |
| `401` | Unauthorized — missing or invalid API key              |
| `403` | Forbidden — API key lacks permission for this resource |
| `404` | Not Found — resource does not exist                    |
| `429` | Too Many Requests — rate limit exceeded                |
| `500` | Internal Server Error — unexpected failure             |

Error responses include a JSON body:

```json theme={null}
{
  "error": {
    "code": 400,
    "message": "input is required"
  }
}
```

## API Categories

| Category                                  | Description                                          |
| ----------------------------------------- | ---------------------------------------------------- |
| [Traces](/api-reference/traces-api)       | Log, list, and inspect AI call traces                |
| [Scoring](/api-reference/scoring-api)     | Attach scores to traces manually or via LLM judges   |
| [Analytics](/api-reference/analytics-api) | Query metrics, costs, performance, and export logs   |
| [Testing](/api-reference/testing-api)     | Create test suites, run evaluations, view results    |
| [Versions](/api-reference/versions-api)   | Publish, compare, and rollback prompt/model versions |

## Quick Start

Log a trace with a single cURL call:

```bash theme={null}
curl -X POST https://api.trainlyai.com/v1/proj_abc123/traces \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Summarize this document.",
    "output": "The document describes quarterly revenue growth of 12%.",
    "model": "gpt-4o",
    "latency_ms": 842.5,
    "token_usage": {
      "prompt_tokens": 320,
      "completion_tokens": 45,
      "total_tokens": 365
    },
    "tags": ["summarization", "production"],
    "status": "success"
  }'
```

Response:

```json theme={null}
{
  "trace_id": "trc_9f8e7d6c5b4a",
  "status": "created"
}
```