Quickstart

1. Start with an application key

Open Settings → API keys and choose Create key for your application; the Backend preset fits this quickstart. A workspace administrator can create a key. Save it when it is shown; the secret is displayed once.

A key can call only the routes its capabilities allow. The Backend preset includes what this quickstart needs: Create users and computers (users:write), Create and cancel jobs (jobs:write), and Read jobs and artifacts (jobs:read). Choose Custom to add others, such as flows:run or assistants, when you use those APIs. A request outside the key’s capabilities returns 403.

Store it in your backend environment. Each key can access only its own application’s users, jobs, and connections. Keep your existing login system and pass your own user IDs when registering users.

# Local development. For deployment, replace the origin with your dashboard's URL.
TRICKROOM_API_URL=http://localhost:3000/v1
TRICKROOM_API_KEY=tak_replace_with_your_backend_key

2. Register a user

Use the stable user ID from your app as external_id. Repeating this request reuses the same user within this application. Save the returned usr_… ID for subsequent requests.

curl --fail-with-body "$TRICKROOM_API_URL/users" \
  -H "Authorization: Bearer $TRICKROOM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"external_id":"customer_123"}'

For shell examples, export the environment variables above first. The application is inferred from your key; you don’t need to send an application ID.

3. Submit your first job

This example runs a text task without provisioning a computer. Replace usr_REPLACE with your user ID. Computer tasks use execution_mode: "computer" and need a computer assigned to the user.

curl --fail-with-body "$TRICKROOM_API_URL/jobs" \
  -H "Authorization: Bearer $TRICKROOM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: first-summary-123' \
  -d '{"user_id":"usr_REPLACE","execution_mode":"tools","task":"Summarize this text: Our team shipped its first release."}'

A 202 response means the job was accepted. Save its id to follow execution. Reuse the same idempotency key and identical input when retrying a request; use a new key for a new task.

const response = await fetch(process.env.TRICKROOM_API_URL + "/jobs", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.TRICKROOM_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "first-summary-123",
  },
  body: JSON.stringify({
    user_id: "usr_REPLACE",
    execution_mode: "tools",
    task: "Summarize this text: Our team shipped its first release.",
  }),
});
const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.message + " (" + result.error.request_id + ")");
}
console.log(result.id);

4. Follow progress and collect evidence

Read GET /jobs/{id} for status, or subscribe to server-sent events from your backend and forward updates to your UI.

curl -N "$TRICKROOM_API_URL/jobs/job_REPLACE/events/stream?after=0" \
  -H "Authorization: Bearer $TRICKROOM_API_KEY"

Persist the last applied event sequence. Reconnect with Last-Event-ID or after to replay durable events. Deduplicate repeats and ignore unknown event types.

Terminal statuses are completed, failed, cancelled, and timed_out. Read /jobs/{id}/report for verification and /jobs/{id}/artifacts for saved evidence. Completion and verification are separate outcomes.

5. Connect the services your users need

In an application’s Integrations tab, enable the services a job may use and choose their approval policy. Connect each account to a specific app user. A plugin permission enables a capability; a user connection provides access to that user’s account.

Use the dashboard’s supported OAuth or token connection flow. Keep provider tokens on your server. For public web search and reading, set the application’s policy in Settings → Web access, then request web access on the job.

6. Turn repeatable tasks into flows

Create a flow in the application’s Flows tab, then call POST /applications/{id}/flows/{flowId}/run with its current version, a user, inputs, and an idempotency key. A run returns a job you can observe with the same endpoints.

Runs preserve their flow definition and version. After editing or archiving a flow, use the saved job ID to observe an earlier run. Flow steps execute as instructions within a job and do not have independent crash checkpoints.

7. Connect a chat assistant

A messaging backend can create an assistant and a conversation under /v1/applications/{id}, then submit chat input to /conversations/{conversationId}/messages. Save the returned job ID. Every assistant mutation requires an Idempotency-Key; reuse the same key and payload when a submission times out. Your backend owns channel authentication and maps each channel user to a Trickroom user and conversation.

Create a delivery subscription, poll its /events endpoint, and deliver message.ready events through your channel. Apply consent and quiet hours there. Persist handled events and pending acknowledgements, then send the handled cursor to /ack. Retry a failed acknowledgement with the same key even when the next poll contains only events you already handled. Each batch contains up to 100 events; the server replays them until acknowledged.

Use the application key to inspect jobs, download artifact bytes, and read GET /v1/approvals?status=pending. Follow every next_cursor within an inbox refresh, starting the next refresh at zero. A human decision uses a separate key with approvals:decide and POST /v1/approvals/{id}/approve or /reject. Send the target user_id, the authenticated human's actor_external_id, and the details_hash from the exact request shown on their card. Keep both keys on your backend.

The customer API contract

Browse the API reference →

The OpenAPI document describes request fields, response schemas, and application-key operations, including assistants and subscriptions. Delegated approval decisions use a separate interface and are not included in this document. Import it into your API client or use it to generate a client library.

Pagination

User, job, and event lists accept after and limit (up to 200). Pass the returned next_cursor to continue.

Errors

JSON errors include error.code, error.message, and error.request_id. Use the code for handling and the request ID for diagnostics.

Retries

Job and flow submissions accept Idempotency-Key. Flow runs require it or the equivalent body field. Changed input with the same key returns 409.

Versioning

The base path is /v1. Allow additive response fields and event types.