API Reference

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:

{
  "error": {
    "code": 400,
    "message": "input is required"
  }
}

API Categories

Category	Description
Traces	Log, list, and inspect AI call traces
Scoring	Attach scores to traces manually or via LLM judges
Analytics	Query metrics, costs, performance, and export logs
Testing	Create test suites, run evaluations, view results
Versions	Publish, compare, and rollback prompt/model versions

Quick Start

Log a trace with a single cURL call:

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:

{
  "trace_id": "trc_9f8e7d6c5b4a",
  "status": "created"
}

Overview

APIs

Base URL

Authentication

Rate Limiting

Response Format

Error Codes

API Categories

Quick Start

​Base URL

​Authentication

​Rate Limiting

​Response Format

​Error Codes

​API Categories

​Quick Start

Base URL

Authentication

Rate Limiting

Response Format

Error Codes

API Categories

Quick Start