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 are granted the chat scope, which covers the session and messaging endpoints below.

• Keys are shown once at creation — store them somewhere safe.
• Revoke any key at any time; revoking kills all requests made with it.
• Keys are scoped to your account and give access to your AIs and their capabilities.

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",
  "projectId": null,
  "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.

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.