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://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 four 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. |
| platform-admin | Requires platform-admin privileges. |
Authentication
Account creation, sign-in, email verification, password reset, and 2FA flows.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /auth/token | public | Exchange a platform API key for a short-lived JWT bearer token. |
| POST | /auth/register | public | Create an email/password account. Always returns the same anti-enumeration message. |
| POST | /auth/login | public | Authenticate with email and password. Returns an access token or a 2FA challenge. |
| POST | /auth/verify-email | public | Verify email address using the token from the verification email. |
| POST | /auth/resend-verification | public | Request a new verification email. Always returns a generic success message. |
| POST | /auth/request-password-reset | public | Send a password reset link. Always returns the same anti-enumeration message. |
| POST | /auth/reset-password | public | Reset a password using the token from the email reset flow. |
| POST | /auth/2fa/enable | full-auth | Start 2FA enablement for the signed-in user by sending an email verification code. |
| POST | /auth/2fa/confirm-enable | full-auth | Confirm 2FA enablement and return the generated backup codes. |
| POST | /auth/2fa/disable | full-auth | Disable 2FA with a valid email code or backup code. |
| GET | /auth/2fa/status | full-auth | Return the current 2FA state for the signed-in user. |
| POST | /auth/2fa/verify | public | Finish a 2FA login challenge using the temporary token from /auth/login. |
Expand an endpoint below for request and response details.
Public routes
Hosted-surface endpoints that do not require a bearer credential.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | public | Health check. Returns service status and version. |
| GET | /stats | public | Return public product counters used on the public site. |
| GET | /metrics | public | Return public metrics for marketing and dashboard summaries. |
| POST | /waitlist | public | Submit a public beta-access request for the current TRW rollout. |
| POST | /contact | public | Submit the public contact form. Uses a honeypot field and email rate limiting. |
Expand an endpoint below for request and response details.
Organization-scoped data
Telemetry, learnings, installations, and release-distribution routes authenticated with a platform API key.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /telemetry | api-key | Submit a telemetry batch for the authenticated organization. |
| GET | /telemetry/stats | api-key | Return aggregated telemetry stats for the authenticated organization. |
| GET | /telemetry/hourly | api-key | Return hourly telemetry buckets for charts and trend views. |
| GET | /telemetry/events | api-key | List raw telemetry events for the authenticated organization. |
| GET | /installations | api-key | List distinct installations derived from telemetry for the authenticated organization. |
| POST | /learnings | api-key | Publish or update a shared learning entry for the authenticated organization. |
| POST | /learnings/search | api-key | Search learnings with keyword filters and optional embedding similarity. |
| GET | /learnings | api-key | List learnings for the authenticated organization. |
| GET | /learnings/{learning_id} | api-key | Return one learning by ID. |
| PATCH | /learnings/{learning_id}/status | api-key | Change a learning status to active, resolved, or obsolete. |
Expand an endpoint below for request and response details.
Platform admin
Cross-organization operational routes for platform admins.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /admin/stats | platform-admin | Return platform-wide statistics for the admin dashboard. |
| GET | /admin/telemetry/aggregate | platform-admin | Return platform-wide telemetry aggregates. |
| GET | /admin/installations | platform-admin | List installations across all organizations. |
| GET | /admin/audit-events | platform-admin | List audit events with optional action and time-window filters. |
| GET | /admin/users | platform-admin | List all users. Platform admin only. |
| GET | /admin/organizations | platform-admin | List all organizations. Platform admin only. |
| GET | /admin/api-keys | platform-admin | List API keys across organizations. Platform admin only. |
| GET | /waitlist | platform-admin | List waitlist entries. This is a platform-admin endpoint even though it is not under /admin. |
Expand an endpoint below for request and response details.
Releases
Release metadata and installer distribution routes used by hosted clients.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /releases/latest | api-key | Get metadata for the latest TRW release. |
| GET | /releases | api-key | List releases for a given channel. |
| GET | /releases/{version}/artifact | api-key | Return artifact metadata for a specific release. |
| GET | /releases/{version}/download | api-key | Return a direct or pre-signed download URL for a release artifact. |
| GET | /releases/latest/installer | api-key | Redirect to the latest installer artifact for the requested channel. |
Expand an endpoint below for request and response details.
Examples
Common API operations using curl.
curl -X POST https://trwframework.com/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key": "trw_live_..."}'
# Response:
# { "access_token": "eyJ...", "token_type": "bearer" }curl https://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://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-..."
}Tip
When you run the backend locally, FastAPI serves interactive OpenAPI docs on the backend origin at /docs .
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.