TRWDocumentation

API Reference

The TRW platform exposes a REST API for authentication, learning management, telemetry, and administration. All endpoints are prefixed with /v1.

Base URL: https://trwframework.com/v1

Authentication

Most endpoints require authentication. TRW supports two methods:

JWT Bearer Token — Obtain via POST /auth/token with email + password. Pass as Authorization: Bearer <token>

API Key — Generated in the admin panel. Pass as Authorization: Bearer trw_live_...

Auth Badges

Each endpoint shows one of four auth badges:

Badge	Meaning
public	No authentication required.
jwt	Requires a valid JWT bearer token.
api-key	Requires a platform API key.
admin	Requires JWT token with admin role.

Authentication

Method	Path	Auth	Description
POST	/auth/token	public	Exchange email + password for a short-lived JWT bearer token.
POST	/auth/register	public	Create a new account. Sends a verification email.
POST	/auth/verify-email	public	Verify email address using the token from the verification email.
POST	/auth/forgot-password	public	Request a password reset email.
POST	/auth/reset-password	public	Reset password using the token from the reset email.
POST	/auth/2fa/enable	jwt	Enable two-factor authentication. Returns a TOTP secret and QR code URI.
POST	/auth/2fa/verify	jwt	Verify a TOTP code to complete 2FA setup or authenticate.

POST/auth/tokenpublic

Exchange email + password for a short-lived JWT bearer token.

Request body:

{ "email": "user@example.com", "password": "..." }

Response:

{ "access_token": "eyJ...", "token_type": "bearer", "expires_in": 3600 }

POST/auth/registerpublic

Create a new account. Sends a verification email.

Request body:

{ "email": "user@example.com", "password": "...", "name": "Ada Lovelace" }

Response:

{ "id": "usr_abc123", "email": "user@example.com", "verified": false }

POST/auth/verify-emailpublic

Verify email address using the token from the verification email.

Request body:

{ "token": "verify_token_..." }

Response:

{ "verified": true }

POST/auth/forgot-passwordpublic

Request a password reset email.

Request body:

{ "email": "user@example.com" }

Response:

{ "sent": true }

POST/auth/reset-passwordpublic

Reset password using the token from the reset email.

Request body:

{ "token": "reset_token_...", "new_password": "..." }

Response:

{ "reset": true }

POST/auth/2fa/enablejwt

Enable two-factor authentication. Returns a TOTP secret and QR code URI.

Response:

{ "secret": "JBSWY3DPEHPK3PXP", "otpauth_uri": "otpauth://totp/..." }

POST/auth/2fa/verifyjwt

Verify a TOTP code to complete 2FA setup or authenticate.

Request body:

{ "code": "123456" }

Response:

{ "verified": true }

Core

Health checks, telemetry ingestion, learning management, and installation tracking.

Method	Path	Auth	Description
GET	/health	public	Health check. Returns service status and version.
POST	/telemetry/events	api-key	Submit a batch of anonymized telemetry events.
GET	/learnings	jwt	List learnings for the authenticated organization. Supports pagination and filtering.
POST	/learnings	jwt	Create a new learning entry.
PATCH	/learnings/{id}	jwt	Update a learning entry. Commonly used to change status or add tags.
GET	/installations	jwt	List TRW installations for the authenticated organization.

GET/healthpublic

Health check. Returns service status and version.

Response:

{ "status": "ok", "version": "0.3.0" }

POST/telemetry/eventsapi-key

Submit a batch of anonymized telemetry events.

Request body:

{ "events": [{ "event_type": "tool_use", "ts": "2026-02-22T10:00:00Z", "data": {} }] }

Response:

{ "accepted": 3 }

GET/learningsjwt

List learnings for the authenticated organization. Supports pagination and filtering.

Response:

{ "items": [...], "total": 342, "page": 1, "page_size": 50 }

POST/learningsjwt

Create a new learning entry.

Request body:

{ "summary": "SQLite WAL mode required for concurrent reads", "detail": "...", "tags": ["sqlite"] }

Response:

{ "id": "L-abc123", "summary": "...", "created_at": "2026-02-22T10:00:00Z" }

PATCH/learnings/{id}jwt

Update a learning entry. Commonly used to change status or add tags.

Request body:

{ "status": "resolved", "tags": ["sqlite", "fixed"] }

Response:

{ "id": "L-abc123", "status": "resolved", "updated_at": "2026-02-22T11:00:00Z" }

GET/installationsjwt

List TRW installations for the authenticated organization.

Response:

{ "items": [{ "id": "inst_...", "project": "my-app", "last_seen": "..." }], "total": 5 }

Admin

Organization and user management. All admin endpoints require the admin role.

Method	Path	Auth	Description
GET	/admin/users	admin	List all users. Admin only.
GET	/admin/organizations	admin	List all organizations. Admin only.
GET	/admin/waitlist	admin	List waitlist entries. Admin only.

GET/admin/usersadmin

List all users. Admin only.

Response:

{ "items": [{ "id": "usr_...", "email": "...", "role": "member" }], "total": 24 }

GET/admin/organizationsadmin

List all organizations. Admin only.

Response:

{ "items": [{ "id": "org_...", "name": "Acme Corp", "member_count": 8 }], "total": 3 }

GET/admin/waitlistadmin

List waitlist entries. Admin only.

Response:

{ "items": [{ "email": "...", "signed_up_at": "..." }], "total": 156 }

Releases

Release metadata and installer downloads.

Method	Path	Auth	Description
GET	/releases/latest	public	Get metadata for the latest TRW release.
GET	/releases/latest/installer	api-key	Download the self-contained installer script.

GET/releases/latestpublic

Get metadata for the latest TRW release.

Response:

{ "version": "0.13.0", "published_at": "2026-03-02", "changelog_url": "..." }

GET/releases/latest/installerapi-key

Download the self-contained installer script.

Response:

# Python installer script (binary download)

Examples

Common API operations using curl.

Get a JWT token

curl -X POST https://trwframework.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}'

# Response:
# { "access_token": "eyJ...", "token_type": "bearer", "expires_in": 3600 }

List learnings

curl https://trwframework.com/v1/learnings?page=1&page_size=10 \
  -H "Authorization: Bearer eyJ..."

# Response:
# { "items": [...], "total": 342, "page": 1, "page_size": 10 }

Submit telemetry

curl -X POST https://trwframework.com/v1/telemetry/events \
  -H "Authorization: Bearer trw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"events": [{"event_type": "session_start", "ts": "2026-03-14T10:00:00Z"}]}'

# 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:

X-RateLimit-Limit: 500

X-RateLimit-Remaining: 498

X-RateLimit-Reset: 1709200000

Error Format

All errors return a consistent JSON shape with an HTTP status code, error type, and message.

Error response

// 401 Unauthorized
{
  "detail": "Invalid or expired token"
}

// 422 Validation Error
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error"
    }
  ]
}

// 429 Too Many Requests
{
  "detail": "Rate limit exceeded. Retry after 60 seconds."
}

Tip

Interactive API docs (Swagger UI) are available at http://localhost:5002/api-docs when running locally.

Next Steps

Deployment

Deploy the platform for your team

Configuration

All config options for the MCP server

MCP Tools

The 24 MCP tools your AI agent uses

Configuration Deployment