Docs
API reference
This page covers the hosted TRW platform API. You do not need these endpoints for the day-to-day repo-local workflow itself; use them when you are integrating auth, telemetry, releases, or other hosted surfaces. All backend routes are prefixed with /v1.
Base URL: https://api.trwframework.com/v1
How access works
Most operational routes are organization-scoped and authenticated with a platform API key. Public auth and onboarding endpoints stay open, but the data-bearing routes assume approved hosted access.
Authorization: Bearer trw_live_...POST /auth/token when you need one.Authorization: Bearer <token>Auth badges
Each endpoint shows one of three auth badges:
| Badge | Meaning |
|---|---|
| public | No bearer credential required. |
| api-key | Requires a platform API key scoped to one organization. |
| full-auth | Requires a signed-in user session or JWT-backed auth context. |
Authentication
Account creation, sign-in, email verification, password reset, and 2FA flows.
Browse each endpoint below. Expand an endpoint for request and response details.
Public routes
Hosted-surface endpoints that do not require a bearer credential.
Browse each endpoint below. Expand an endpoint for request and response details.
Organization-scoped data
Telemetry, learnings, installations, and release-distribution routes authenticated with a platform API key.
Browse each endpoint below. Expand an endpoint for request and response details.
Releases
Release metadata and installer distribution routes used by hosted clients.
Browse each endpoint below. Expand an endpoint for request and response details.
Examples
Common API operations using curl.
curl -X POST https://api.trwframework.com/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key": "trw_live_..."}'
# Response:
# { "access_token": "eyJ...", "token_type": "bearer" }curl https://api.trwframework.com/v1/learnings?page=1&page_size=10 \
-H "Authorization: Bearer trw_live_..."
# Response:
# { "items": [...], "total": 342, "page": 1, "page_size": 10 }curl -X POST https://api.trwframework.com/v1/telemetry \
-H "Authorization: Bearer trw_live_..." \
-H "Content-Type: application/json" \
-d '{"events": [{"event_type": "session_start", "session_id": "run_123", "status": "ok"}]}'
# Response:
# { "accepted": 1 }Rate limiting
All endpoints are rate-limited. When you exceed the limit, the API returns 429 Too Many Requests. Rate limit headers are included in every response:
Error format
Application errors are normalized to a flat JSON shape with an error code, a human-readable detail string, and a request ID for correlation.
// 401 Unauthorized
{
"error": "unauthorized",
"detail": "Invalid or expired token",
"request_id": "3a8f7f52-..."
}
// 404 Not Found
{
"error": "not_found",
"detail": "Learning not found",
"request_id": "6f4f1b9c-..."
}
// 500 Internal Server Error
{
"error": "internal_server_error",
"detail": "An unexpected error occurred.",
"request_id": "d2a0ab21-..."
}Where to go next
Read configuration if you are wiring a repo install to the hosted platform. Read troubleshooting for auth, proxy, or environment issues. Read tools if your real integration surface is MCP rather than REST.