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

# Overview

# EvalGate REST API overview

> Everything you need to call the EvalGate REST API: base URL, authentication, response format, error envelope, versioning, and available endpoint groups.

The EvalGate REST API gives you programmatic access to evaluations, traces, LLM judges, human annotation tasks, and the authenticated Tool API. Every request goes to a single base URL and returns JSON with camelCase field names. If you prefer a typed client, the [TypeScript SDK](/docs/sdk/typescript) and [Python SDK](/docs/sdk/python) wrap this API and add retries, batching, and caching on top.

## Base URL

All endpoints are served from:

```
https://evalgate.com
```

## Authentication

Every request requires a bearer token in the `Authorization` header:

```bash theme={null} theme={null}
curl https://evalgate.com/api/evaluations \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Get your API key from **Developer Dashboard → Settings → API Keys**. See [API authentication](/docs/api/authentication) for the full details, including scope errors and the organization ID environment variable.

## Response format

All responses are JSON. Field names use camelCase throughout:

```json theme={null} theme={null}
{
  "id": 42,
  "name": "Chatbot regression",
  "type": "unit_test",
  "status": "active",
  "organizationId": "00000000-0000-4000-8000-000000000001",
  "createdAt": "2026-03-15T10:30:00.000Z",
  "updatedAt": "2026-03-15T10:30:00.000Z"
}
```

## Standard error envelope

All error responses use this shape, regardless of status code:

```json theme={null} theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized",
    "details": null,
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

The `requestId` field is a UUID you can include in support tickets to help the team locate the exact request. It also appears in the `x-request-id` response header. See [API error codes](/docs/api/errors) for the full list of codes, HTTP status mappings, and error-handling examples.

## Versioning

The error envelope and all documented response shapes are stable. Breaking changes are versioned and announced before they take effect — you will not encounter silent field removals or type changes on existing endpoints.

## Endpoint groups

| Group                           | Description                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Evaluations](/docs/api/evaluations) | Create evaluation definitions, manage test cases, and start runs                               |
| [Traces](/docs/api/traces)           | Ingest and query LLM traces and spans via the collector or direct CRUD                         |
| [LLM Judge](/docs/api/llm-judge)     | Configure judges, evaluate outputs, and measure judge alignment                                |
| [Annotations](/docs/api/annotations) | Create human labeling tasks and submit labels to build golden datasets                         |
| [Tool API](/docs/api/mcp)            | Authenticated tool discovery and execution (legacy `/api/mcp/*`; not standards-conformant MCP) |

## Rate limits

Limits are applied per organization on a sliding one-minute window:

| Tier       | Limit           |
| ---------- | --------------- |
| Anonymous  | 120 req/min     |
| Free       | 5,000 req/min   |
| Pro        | 25,000 req/min  |
| Business   | 100,000 req/min |
| Enterprise | Custom          |
| MCP tools  | 10,000 req/min  |

When rate limiting is active, responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. A `429` response uses the `RATE_LIMITED` error code.

## SDK alternative

If you are working in TypeScript or Python, the SDKs handle auth, retries, and batching automatically:

* [TypeScript SDK (`@evalgate/sdk`)](/docs/sdk/typescript)
* [Python SDK (`evalgate-sdk`)](/docs/sdk/python)