> ## 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. Most REST surfaces use camelCase field names. The trace collector (`POST /api/collector` and `/api/collector/batch`) is the documented exception and accepts snake\_case wire fields such as `trace_id` and `duration_ms`. Prefer a typed client from the [TypeScript SDK](https://evalgate.com/docs/sdk/typescript.md) or [Python SDK](https://evalgate.com/docs/sdk/python.md) when you want retries, batching, and caching on top.

## Base URL

All endpoints are served from:

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

## Authentication

Customer-data operations require 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 **Settings → API keys** in the EvalGate app. See [API authentication](https://evalgate.com/docs/api/authentication.md) for the full details, including scope errors and the organization ID environment variable.

To exercise deterministic assertions before connecting customer data, use the
credential-free [API test mode](https://evalgate.com/docs/platform/api-test-mode.md). It saves no evaluation
results, invokes no model provider and creates no billable result.

## Response format

All responses are JSON. Field names use camelCase on the general REST API.
Scope snake\_case request fields to `/api/collector` (and its batch route); see
[Traces API](https://evalgate.com/docs/api/traces.md). Example camelCase resource payload:

```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",
    "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](https://evalgate.com/docs/api/errors.md) 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](https://evalgate.com/docs/api/evaluations.md) | Create evaluation definitions, manage test cases, and start runs |
| [Traces](https://evalgate.com/docs/api/traces.md) | Ingest and query LLM traces and spans via the collector or direct CRUD |
| [LLM Judge](https://evalgate.com/docs/api/llm-judge.md) | Configure judges, evaluate outputs, and compare judges with human labels |
| [Annotations](https://evalgate.com/docs/api/annotations.md) | Create human labeling tasks and submit labels to build golden datasets |
| [MCP and Tool API](https://evalgate.com/docs/api/mcp.md) | Authenticated read-only MCP review endpoint plus legacy HTTP Tool API |

## Rate limits

Default limits depend on the request context; individual routes can apply their own tier:

| Request context | Limit |
| - | - |
| Anonymous utility requests | 100 requests/hour |
| Signed-in member sessions | 5,000 requests/day |
| Owner and admin sessions | 50,000 requests/day |
| API keys and MCP tools | 100,000 requests/day |

Responses that reach rate-limit admission include `RateLimit-Policy`, `RateLimit`,
numeric `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and legacy
`X-RateLimit-*` fields. `RateLimit-Reset` is a delay in seconds;
`X-RateLimit-Reset` remains a Unix timestamp in milliseconds. Throttled admission
returns `429`, error code `RATE_LIMITED`, and `Retry-After` seconds. Infrastructure
health checks have no request quota; shared-cacheable public responses omit
per-caller quota hints. See [Rate limits](https://evalgate.com/docs/platform/rate-limits.md).

## SDK alternative

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.