Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

Use this file to discover all available pages before exploring further.

By default, Titan API requests wait for the operation to complete before returning a response. For most calls this is fine, but when you’re sending a high volume of messages, running bulk operations, or simply don’t need to wait for the result, the synchronous pattern becomes a bottleneck. Async mode flips this: Titan acknowledges your request immediately and delivers the result to your webhook once the operation finishes.

​
How it works

Add the Prefer: respond-async header to any API request. Instead of waiting for the result, Titan returns 202 Accepted with a correlation ID. When the operation completes, Titan sends a command.result webhook event containing the result and the same correlation ID so you can match it to the original request.
Set up a webhook subscribed to command.result events before you start using async mode, or you’ll receive the 202 but never see the result.

​
Sending an async request

curl -X POST https://api.example.com/api/messages/send \
  -H "Authorization: Bearer titan_..." \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "default",
    "chatId": "[email protected]",
    "type": "text",
    "text": "Hello!"
  }'
Response — 202 Accepted: 
{
  "data": {
    "correlationId": "cmd-abc123"
  }
}
Save the correlationId. You’ll use it to match the incoming webhook event to this specific request.

​
The command.result webhook event

When the operation completes, Titan delivers a command.result event to your registered webhook: 
{
  "event": "command.result",
  "session": "default",
  "data": {
    "correlationId": "cmd-abc123",
    "success": true,
    "result": {}
  }
}
The correlationId in the webhook payload matches the one returned by the 202 response. The result object contains the same data you would have received synchronously. If the operation fails, success will be false and result will contain the error details.

​
When to use async mode

When you need to send messages to hundreds or thousands of recipients, async mode lets you fire all the requests without blocking on each one. Your webhook handler receives results as they complete.
Some operations — like QR code pairing that waits for a scan — can take seconds or longer. Async mode frees your request thread immediately.
If your application uses a queue-based architecture, async commands map cleanly onto that pattern: enqueue the API call, process results from the command.result queue.
Async mode works with any API endpoint that forwards commands to the Titan runner. The Prefer: respond-async header is ignored on endpoints that return data directly without forwarding a command (for example, read-only GET requests).

​
Correlating requests to results

A typical pattern is to store the correlationId alongside the job in your own database when you fire the request, then look up the job when the webhook arrives:
1

Fire the request and store the correlation ID

Send the API request with Prefer: respond-async. Save the returned correlationId in your database alongside any context you need (user ID, job type, etc.).
2

Receive the webhook

When the command.result event arrives at your webhook endpoint, extract the correlationId from data.correlationId.
3

Look up the original job

Query your database for the record matching that correlationId and process the result accordingly.

​
Webhook setup

Register a webhook that subscribes to command.result if you haven’t already: 
POST /api/webhooks
Authorization: Bearer titan_...
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/titan",
  "events": ["command.result"]
}
See Webhooks overview for full webhook configuration options, including HMAC signature verification and retry policies.