API Reference

This section provides complete documentation for all Labs API endpoints.

Base URL

Base URL:

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer $LABS_API_KEY

Get your API key from the Labs Portal.

Response Format

All responses are JSON with consistent structure:

Success Response

{
  "field1": "value",
  "field2": 123,
  "request_id": "req_01jk..."
}

Error Response

{
  "message": "Human-readable description",
  "data": {
    "request_id": "req_01jk..."
  }
}

The HTTP status code indicates the error type.

Request IDs

Every response includes a request_id for tracing and support:

Success responses: top-level request_id field in the JSON body
Error responses: data.request_id field in the JSON body
All responses: X-Request-ID response header

Include the request_id when reporting issues.

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request — Invalid input
401	Unauthorized — Invalid or missing API key
403	Forbidden — No access to resource
404	Not Found — Resource doesn’t exist
429	Rate Limited — Too many requests
500	Server Error — Something went wrong

Rate Limiting

Rate limits are included in response headers:

Header	Description
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Requests left in window
`X-RateLimit-Reset`	Unix timestamp when window resets

Endpoint Categories

Catalog

Browse available collections and scenarios

Episodes

Multi-turn training sessions

Evaluation

Score conversations and compare responses

OpenAPI Specification

The complete OpenAPI 3.1 specification is available at: You can use this with tools like Swagger UI or import into Postman.

Overview

Catalog

Episodes

Evaluation

Key

Training Datasets

Base URL

Authentication

Response Format

Success Response

Error Response

Request IDs

HTTP Status Codes

Rate Limiting

Endpoint Categories

Catalog

Episodes

Evaluation

OpenAPI Specification

​Base URL

​Authentication

​Response Format

​Success Response

​Error Response

​Request IDs

​HTTP Status Codes

​Rate Limiting

​Endpoint Categories

Catalog

Episodes

Evaluation

​OpenAPI Specification

Base URL

Authentication

Response Format

Success Response

Error Response

Request IDs

HTTP Status Codes

Rate Limiting

Endpoint Categories

OpenAPI Specification