API & Webhooks

Tyrex AI exposes a straightforward API for developers who want to build on top of their AIs, plus webhook triggers so external systems can start workflows.

API keys

Create and manage API keys from Settings → API keys. Keys use the tx_live_ prefix and carry one or more scopes that decide which endpoints they can call.

Keys are created with chat when you don't pick scopes. The authoritative list is served by the API at GET /api-keys/scopes — read it from there instead of hardcoding it, so your client can't drift from the server.

• Keys are shown once at creation — store them somewhere safe.
• Revoke any key at any time; revoking kills all requests made with it.
• A key only reaches endpoints that accept API keys. Calling one outside its scopes returns 403 naming the missing scope.

Base URL

https://aiapi.tyrex.id/api/v1

Authenticate by sending your API key as a bearer token on every request:

Authorization: Bearer <your-api-key>

Response envelope

Every successful response is wrapped in a standard envelope:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-08-12T09:00:00.000Z",
  "path": "/api/v1/ai/sessions"
}

The examples below show the data payload for readability. Errors use a different envelope — see Error handling.

Endpoints

List sessions

GET /ai/sessions?limit=20&cursor=<last-session-id>
Authorization: Bearer <your-api-key>

Returns your sessions, newest first, cursor-paginated:

{
  "items": [
    {
      "id": "sess_...",
      "type": "GENERAL",
      "status": "ACTIVE",
      "title": "Order triage",
      "updatedAt": "2026-08-12T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}

nextCursor is null when there are no more pages.

Chat with your AI

1. Create a session

POST /ai/sessions
Authorization: Bearer <your-api-key>

{
  "title": "Order triage",
  "personaId": "...",
  "initialMessage": "Help me triage today's orders"
}

POST /ai/sessions is idempotent — send the same Idempotency-Key header on a retry and you won't create two sessions or double-charge.

Request fields

Response

{
  "id": "sess_...",
  "type": "GENERAL",
  "status": "ACTIVE",
  "title": "Order triage",
  "personaId": "...",
  "createdAt": "2026-08-12T09:00:00.000Z",
  "updatedAt": "2026-08-12T09:00:00.000Z"
}

2. Send a message

Send a message to an existing session. The reply is returned in full in a single synchronous response.

POST /ai/sessions/<session-id>/messages
Authorization: Bearer <your-api-key>

{
  "content": "Summarize my uploaded document",
  "model": "tyrex1.5:carno"
}

Request fields

Response

{
  "userMessage": {
    "id": "msg_...",
    "role": "USER",
    "content": "Summarize my uploaded document",
    "attachments": null,
    "createdAt": "2026-08-12T09:01:00.000Z"
  },
  "assistantMessage": {
    "id": "msg_...",
    "role": "ASSISTANT",
    "content": "Here is a summary of your uploaded document...",
    "thinking": null,
    "createdAt": "2026-08-12T09:01:04.000Z"
  },
  "tokensUsed": 1240
}

• assistantMessage.thinking holds the model's reasoning trace when present (this session's AI has thinking enabled).
• tokensUsed reports consumption for the turn and is reflected in your usage meters.

Streaming mode

For long responses, pass ?stream=true on the URL. The request is queued and runs in the background, and the response is delivered over the realtime channel instead of as a single body:

POST /ai/sessions/<session-id>/messages?stream=true
Authorization: Bearer <your-api-key>

{
  "content": "Analyze this report"
}

{
  "sessionId": "sess_...",
  "turnId": "...",
  "status": "queued",
  "deliverVia": "ws:/ai-assistance"
}

• The work continues even if the HTTP connection drops — the turn is tracked by turnId.
• Chunks arrive over the ai-assistance realtime channel; reconnect and replay using turnId.

Webhook triggers for workflows

Any workflow with a Webhook trigger exposes a public URL you can call from your own systems. The secret is generated by Tyrex when you pick the trigger — no bearer token needed, the secret is the credential.

POST /workflows/webhook/<workflow-id>/<secret>
Content-Type: application/json

{
  "orderId": "ORD-8831",
  "customerEmail": "[email protected]",
  "items": 3
}

The request body is passed to the workflow as its input payload. Use cases: a store backend starts the order-triage workflow, a form submission starts a follow-up, a monitoring tool starts an alert workflow.

• Rotate the secret any time with POST /workflows/<workflow-id>/webhook/rotate (API key required). The old secret stops working immediately.
• A 200 response means the run was accepted — check the workflow's run log for the result.
• Repeated calls with the same payload within 5 minutes are deduplicated, so safe retries from your side won't double-run.
• Runs are logged and metered like any other run.

Versioning & deprecation

The API is versioned in the URL path — everything on this page lives under /api/v1. Every response also carries an X-API-Version header, so a client can confirm which contract it's talking to without parsing the path:

X-API-Version: v1

When an endpoint is being retired it keeps working, but starts returning deprecation headers (RFC 8594 / RFC 9745 / RFC 8288) so clients can migrate on their own schedule instead of discovering it from a 404:

Deprecation: true
Sunset: Fri, 01 Jan 2027 00:00:00 GMT
Link: </api/v1/replacement/path>; rel="successor-version"
X-Deprecation-Note: Use the lighter endpoint instead

Deprecated endpoints are never removed before their Sunset date, and a successor is always named in Link. If you receive no deprecation headers, nothing on that endpoint is going away.

Rate limits & usage

• API requests consume the same usage units as chat in the app — the meters in your dashboard reflect combined usage.
• Webhook calls are subject to per-workflow rate limits to prevent runaway loops.

Error handling

The API uses standard HTTP status codes:

Errors share one envelope:

{
  "status": 402,
  "message": "Monthly unit quota exhausted",
  "extensions": {
    "code": "INSUFFICIENT_CREDITS",
    "servicePath": "/api/v1/ai/sessions/sess_.../messages",
    "timestamp": "2026-08-12T09:05:00.000Z",
    "details": {
      "error": "INSUFFICIENT_CREDITS",
      "required": 1200,
      "remaining": 0
    }
  }
}

Structured error codes carried in extensions.details:

Validation failures return 400 with per-field errors in extensions.errors:

{
  "status": 400,
  "message": "Validation failed",
  "extensions": {
    "code": "ER:400",
    "errors": [
      { "field": "message", "message": "message must be a string" }
    ]
  }
}

Security

• All API traffic is HTTPS.
• Keys are revocable and never stored in readable form after creation.
• Webhook URLs contain a 48-character random secret — keep them private and rotate after any suspected leak.
• Webhook tools and endpoints are validated against server-side request forgery — Tyrex will not fetch internal addresses.

Next: Privacy & Data.