API Reference
Complete REST API reference for the Retrace platform.
Base URL
https://api.retrace.yashbogam.meAll endpoints are versioned under /api/v1/. For local development, use http://localhost:3001.
Authentication
Two authentication methods are supported:
API Key — for SDKs, scripts, and server-to-server communication:
curl -H "x-retrace-key: rt_live_..." https://api.retrace.yashbogam.me/api/v1/tracesBearer Token — for the web application using Clerk-issued JWTs:
curl -H "Authorization: Bearer <jwt>" https://api.retrace.yashbogam.me/api/v1/tracesAll endpoints require authentication unless explicitly noted as public.
Traces
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/traces | Create a trace with optional batch spans |
| GET | /api/v1/traces | List traces (supports limit, offset, status params) |
| GET | /api/v1/traces/:id | Get a single trace with all child spans |
| DELETE | /api/v1/traces/:id | Delete a trace and all associated spans |
Tapes
Tapes are shareable, read-only snapshots of traces.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/tapes | Publish a trace as a shareable tape |
| GET | /api/v1/tapes/:slug | Get tape by slug (public, no auth required) |
| GET | /api/v1/tapes | List public tapes |
Forks
Forks let you branch from any span and replay with modifications.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/forks | Create a fork from a specific span |
| POST | /api/v1/forks/:id/replay | Execute a fork with modified parameters |
| GET | /api/v1/forks/:id/diff | Get the divergence diff between original and fork |
Memory
Persistent semantic memory for agents across sessions.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/memory | Store a memory entry |
| POST | /api/v1/memory/search | Semantic search across memories |
| GET | /api/v1/memory | List all memories (supports scope, category filters) |
| GET | /api/v1/memory/:id | Get a single memory by ID |
| DELETE | /api/v1/memory/:id | Delete a memory entry |
Search
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/search | Semantic search across all spans in your traces |
Accepts query (string) and optional limit (number, default 10).
API Keys
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/api-keys | Generate a new API key |
| GET | /api/v1/api-keys | Check if a key exists for the current user |
| DELETE | /api/v1/api-keys | Revoke the current API key |
Skills
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/skills | Create a skill |
| GET | /api/v1/skills | List skills (supports scope, tags filters) |
| GET | /api/v1/skills/:id | Get a skill by ID |
| PATCH | /api/v1/skills/:id | Update a skill (increments version) |
| DELETE | /api/v1/skills/:id | Delete a skill |
Billing
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/billing/checkout | Create a Dodo Payments checkout session |
| POST | /api/v1/billing/portal | Open the Dodo Payments customer portal |
| POST | /api/v1/billing/webhook | Dodo Payments webhook receiver (no auth) |
Rate Limits
| Tier | Write Endpoints | Read Endpoints |
|---|---|---|
| Free | 100 req/min | 300 req/min |
| Pro | 500 req/min | 1500 req/min |
Rate-limited responses return HTTP 429 with a Retry-After header indicating seconds until the next allowed request.
Error Format
All errors return a consistent JSON structure:
{ "error": "Human-readable error message" }| Status Code | Meaning |
|---|---|
| 400 | Bad request — invalid parameters or body |
| 401 | Unauthorized — missing or invalid credentials |
| 404 | Not found — resource does not exist |
| 429 | Rate limited — too many requests |
| 500 | Internal server error |
[!TIP] Use the
x-request-idresponse header when reporting issues. It helps the team locate your request in server logs.