Pagination · Errors & retries · Documentation changelog

Your first API request

Make a read-only request from your server to list the agents your workspace account can access.

1. Get access and a token

Sign in at app.tuolen.com and open Settings → API Tokens. Create a personal access token and store the value immediately: it is shown only once. Token management requires an org_admin, admin, or developer role. Ask your workspace administrator if you do not have access.

Tuolen onboarding is invite-only. If you do not have an account, request access on the product site. Do not use a publishable widget key for this request.

2. Use the production API origin

https://api.tuolen.com is the production origin. Endpoint paths already include /api; do not add a second prefix. The interactive reference uses the API host that serves this page. If you have a separate test deployment, substitute its origin deliberately.

Set TUOLEN_TOKEN in your server environment or secret manager. Never commit it, put it in frontend code, or include it in a URL. Avoid pasting real credentials into shell history or shared logs.

3. List your agents

# Set TUOLEN_TOKEN securely in your server environment first.
: "${TUOLEN_TOKEN:?Set TUOLEN_TOKEN to your personal access token}"

curl --fail-with-body --silent --show-error --max-time 15 \
  'https://api.tuolen.com/api/agents' \
  --header "Authorization: Bearer $TUOLEN_TOKEN" \
  --header 'Accept: application/json'

// Save as list-agents.mjs. Run with Node.js 20+ on your server.
const token = process.env.TUOLEN_TOKEN;
if (!token) throw new Error('Set TUOLEN_TOKEN in your environment');

const response = await fetch('https://api.tuolen.com/api/agents', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json',
  },
  redirect: 'error',
  signal: AbortSignal.timeout(15_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}; request ID: ${response.headers.get('x-request-id') ?? 'unavailable'}`);
}
console.log(JSON.stringify(await response.json(), null, 2));

The Node.js example needs no package installation. After setting the environment variable, run node list-agents.mjs. Both examples perform only GET /api/agents, with a timeout and no automatic retries.

4. Read the response

A successful request returns HTTP 200 and a data array, not a paginated object. An empty array is valid when no agents are accessible. Below is a synthetic example; its IDs and values are not live workspace data.

{
  "success": true,
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "organizationId": "22222222-2222-4222-8222-222222222222",
      "name": "Support",
      "description": "Customer support assistant",
      "systemPrompt": "You are a helpful assistant.",
      "emailSignature": "",
      "emailSignatureHtml": "",
      "model": null,
      "provider": null,
      "temperature": 0.7,
      "maxTokens": 2048,
      "welcomeMessage": "Hello! How can I help you today?",
      "ratingEnabled": false,
      "inactivityTimeoutMinutes": null,
      "handoffMode": "human",
      "ticketProvider": null,
      "handoffFallbackMinutes": null,
      "requireIdentityVerification": false,
      "initialForm": null,
      "isActive": true,
      "hasIdentitySecret": false,
      "createdAt": "2026-10-04T12:00:00.000Z",
      "updatedAt": "2026-10-04T12:00:00.000Z"
    }
  ]
}

hasIdentitySecret reports configuration, never the secret itself. model and provider may be null. See List agents for the field contract.

What next?

Choose the right credential, page through results, or troubleshoot a failed request.

The right key for the job.

Workspace management, visitor interactions, and reporting use different credentials. Check the security requirement on each operation.

A 401 usually means missing, invalid, expired, or wrong-type credentials. A 403 may indicate role, workspace, membership, origin, or entitlement restrictions. Documentation visibility does not grant access. See errors and retries.

Page through the right shape.

Pagination is operation-specific. Do not assume every list returns data.items, a total count, or a next cursor.

A dashboard conversation page

{
  "success": true,
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "limit": 20,
    "totalPages": 0
  }
}

For knowledge bases and documents, the envelope is different:

{
  "success": true,
  "data": [],
  "pagination": {
    "limit": 100,
    "offset": 0
  }
}

Filters and consistency

Use the query parameters listed on the individual operation. Dashboard conversation search is limited to 200 characters. Reporting supports date, status, rating, and message-inclusion filters; never assume it returns message content by default.

Dashboard conversations are sorted by updatedAt descending. Knowledge bases and documents are sorted by createdAt descending. These lists are not snapshots: concurrent writes can move or remove records while you page. Deduplicate by resource ID, keep filters stable, and use bounded loops.

Handle failure deliberately.

Use the HTTP status first. Error codes and extra fields vary by operation; do not depend on every failure having the same body.

{
  "success": false,
  "error": "Too many requests, please try again later."
}

Many JSON errors also include an optional code. Validation details may be omitted in production. Some operations return other content types or a specialized error result, such as the webhook test endpoint’s HTTP 502 delivery envelope.

Rate-limit budgets

Current default application limits include a general API budget of 100 requests/minute per IP, reporting at 60/minute per API key, authentication at 20 attempts/15 minutes per IP, and widget requests at 30/minute keyed by API key (falling back to IP). Reporting and other routes under /api are also subject to the shared IP budget.

Uploads, token generation, voice, exports, and other routes have additional limits. These defaults are not a reserved throughput allowance. Observe the response rate-limit headers and Retry-After; custom 429 responses may not include that header.

Retry reads, reconcile writes

• For a GET that is documented as read-only, retry transient failures only, with a small attempt cap, a total deadline, and randomized backoff.
• When Retry-After is present, do not retry sooner. If it exceeds your deadline, stop and defer the work.
• Do not blindly retry create, send, payment, import, or delete requests after a timeout. The server or provider may already have acted.
• Tuolen does not provide a global Idempotency-Key header. Use an idempotency field only when the specific operation documents it; a random header does not make a write safe.

Report a problem safely

Capture the HTTP method, redacted path, UTC time, status, and returned X-Request-Id when available. Contact hello@tuolen.com with those details. Remove tokens, signing secrets, provider credentials, customer message content, and sensitive query values from diagnostics.

Let your app listen.

Receive signed outbound events at a public endpoint you control. Webhook configuration requires the paid webhook entitlement.

1. Register your receiver

Use a public HTTP(S) URL; HTTPS is recommended. Replace the example URL below before running the POST. Supported roles are org_admin, admin, and developer. A PATCH must contain at least one supported field.

# This POST creates a real webhook. Use an approved receiver you control.
: "${TUOLEN_TOKEN:?Set TUOLEN_TOKEN to your personal access token}"

curl --fail-with-body --silent --show-error --max-time 15 \
  --request POST 'https://api.tuolen.com/api/webhooks' \
  --header "Authorization: Bearer $TUOLEN_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Conversation events","url":"https://example.com/webhooks/tuolen","events":["conversation.created","conversation.resolved"],"isActive":true}'

If you omit secret, the response returns a generated signingSecret at the top level, once only. Store it securely before closing the response. If you supply a secret (16–500 characters), that field is omitted from the response. Subsequent reads expose hasSecret, never encrypted secret material.

2. Know the event envelope

{
  "id": "66666666-6666-4666-8666-666666666666",
  "event": "conversation.created",
  "createdAt": "2026-10-04T12:00:00.000Z",
  "data": {
    "conversationId": "33333333-3333-4333-8333-333333333333",
    "agentId": "11111111-1111-4111-8111-111111111111",
    "source": "web_widget"
  }
}

Payloads can contain customer content. Apply least-privilege access and your retention policy. The event id identifies this signed delivery, not the underlying conversation or message.

3. Verify the original bytes

Requests use Content-Type: application/json, X-Tuolen-Event, X-Tuolen-Delivery, X-Tuolen-Timestamp (Unix seconds), and X-Tuolen-Signature (sha256=<hex>).

The signature is HMAC-SHA256 of the exact timestamp header, a period, and the original raw request bytes. Capture a Buffer before JSON middleware—for example, a route-specific express.raw({ type: 'application/json', limit: '1mb' }) before express.json(). Choose a body-size limit suitable for your receiver. Do not reserialize JSON for verification.

// Save as verify-tuolen-webhook.mjs. Node.js 20+, server-side only.
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyTuolenWebhook({
  rawBody, timestamp, signature, secret, now = Date.now(),
}) {
  // Reject missing/duplicate headers and malformed signatures before decoding.
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  if (typeof timestamp !== 'string' || !/^[0-9]{1,12}$/.test(timestamp)) return false;
  if (typeof signature !== 'string' || !/^sha256=[a-fA-F0-9]{64}$/.test(signature)) return false;

  const seconds = Number(timestamp);
  const nowSeconds = Math.floor(now / 1000);
  // Receiver policy: at most 5 minutes old, at most 30 seconds in the future.
  if (!Number.isSafeInteger(seconds) || !Number.isFinite(nowSeconds)) return false;
  if (seconds < nowSeconds - 300 || seconds > nowSeconds + 30) return false;

  // rawBody must be the original Buffer, captured BEFORE JSON parsing.
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody)
    .digest();
  const received = Buffer.from(signature.slice(7), 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Pass the raw Buffer, the two signature/timestamp header strings, and your stored secret to verifyTuolenWebhook. Reject verification failures without processing the event. Keep your server clock synchronized; the five-minute age and 30-second future allowance above are receiver policy, not a Tuolen delivery guarantee.

4. Design for best-effort delivery

• Tuolen makes a single best-effort POST with a 10-second timeout.
• There are no automatic retries, durable replay, or ordering guarantees. Do not use webhooks as your sole system of record; reconcile important state through read APIs.
• Only a 2xx response counts as success. Redirects are not followed. Acknowledge promptly after durable acceptance and process asynchronously.
• Delivery logs show the latest 100 records, newest first, with no pagination. Logging is itself best-effort. A log record’s id is not the signed event ID.

Test without surprises

POST /api/webhooks/{id}/test takes no body and sends a real tool.executed event with data: {test: true, organizationId}, even if that event is not selected. This test data differs from an ordinary tool event.

The test API returns HTTP 200 if your receiver responds 2xx, or HTTP 502 with {success: false, data: {success, statusCode, error, durationMs}} on failure. A successful test checks that delivery only; it does not enable retries or prove future availability.

Open the Webhooks reference →

Know what changed.

This changelog records documentation improvements. It does not imply an API behavior change or a new compatibility guarantee.

October 4, 2026 · Documentation update

• Added Docs to the marketing header, mobile navigation and footer, with an API-docs CTA on the integrations page. /docs and /developers redirect to the developer portal.
• Added production onboarding, copyable cURL and Node.js requests, and synthetic JSON examples.
• Documented credential boundaries, pagination, errors, rate limits, safe retry decisions, and actual webhook delivery behavior.
• Expanded request and response contracts for common agent, knowledge, conversation, credential, connection and webhook operations. Corrected bodyless actions, optional visitor-read input, and WhatsApp message success status documentation.
• Added guide-content and operation-description search and explicit notices for incomplete legacy response contracts.

Which version is this?

openapi: 3.1.0 is the specification format. info.version: 1.0.0 identifies the documentation; it does not mean every API path is versioned. Only the reporting API uses the /api/public/v1 prefix. Use operation paths exactly as listed.

Coverage and compatibility

Some older operations still document only a common response envelope. They are marked x-tuolen-response-coverage: envelope-only and include a warning in the reference. Format-only export descriptions are also marked. Do not infer missing fields from Swagger’s generated sample or assume full generated-SDK coverage.

Where runtime validation has conditional rules that cannot be expressed by the schema generator, read the operation notes as well. Plan/provider availability, role checks, and tenant isolation remain enforced at runtime.

No general deprecation notice period or API compatibility SLA is published here. Before adopting an operation whose contract is incomplete, confirm the required fields and behavior with hello@tuolen.com. Monitor this changelog and the OpenAPI specification when updating your integration.