Every endpoint

Show typing in a chat

API key · messages:write

Shows "typing…" or "recording…" to a person or group, or stops (paused). WhatsApp clears it by itself after a short while or when a message arrives. Nothing is stored.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/presence \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "state": "typing"
  }'

Responses

List messages

API key · messages:read

Newest first, cursor paginated. Offsets are not offered: they skip and duplicate.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/messages \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Export delivery metadata as CSV

API key · messages:read

Streamed row by row. Message bodies are not included — this is delivery metadata, not content.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/messages/export \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Send a message

API key · messages:write

Accepts a message for delivery and returns 202. 202 means accepted, never delivered — the message is durably stored and queued, and only the status field ever claims delivery. Send media or location for an attachment, send_at to defer it. Supply Idempotency-Key so a retry cannot send twice. A first message to someone the number has never talked to is checked against WhatsApp and paced: 10 an hour in a number's first week, 30 after, at least 20 seconds apart. Over the pace it stays queued and goes out later; nothing is refused. A message WhatsApp accepts but never confirms sending within 24 hours is failed with not_confirmed.

Body

Request

curl -X POST https://www.chatrail.dev/v1/messages/text \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "connection": "main",
    "to": "+15551234567",
    "body": "Order CR-2048 has shipped.",
    "context": {
      "order_id": "CR-2048",
      "status": "dispatched"
    }
  }'

Responses

Get a message

API key · messages:read

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/messages/:id \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Edit a message

API key · messages:write

Replaces the text of a text message this number sent, within WhatsApp's 15-minute window, and/or its context. Captions cannot be changed after sending. The first text is kept and audited. Editing the text does not change the context the AI answers from: send context too when the correction matters to it (a new gate, a new time). A context-only edit has no window and does not reach WhatsApp.

Parameters

Body

Request

curl -X PATCH https://www.chatrail.dev/v1/messages/:id \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Corrected: viewing is at 3pm, not 2pm.",
    "context": {
      "property": {
        "address": "14 Mill Lane",
        "viewing": "15:00"
      }
    }
  }'

Responses

Cancel a message

API key · messages:write

Only while it has not reached the provider. Once submitted the message exists on somebody's phone and cancelling would be a lie.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/messages/:id/cancel \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Correct which message a reply answers

API key · messages:write

Re-points an inbound reply at the outbound message it actually answers, or unlinks it with null. The engine's original choice is preserved, so corrections measure the correlation rules rather than quietly overwriting them. The previously linked alert reopens for correlation; the newly linked one is marked answered.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/messages/:id/correlation \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reply_to_message_id": "019bf4a1-0000-7000-8000-000000000000"
  }'

Responses

Download an inbound attachment

API key · messages:read

Streams the file from the transport through ChatRail. Inbound only: an outbound attachment's URL is one the caller supplied and already has. The response carries the stored content type, never the transport's, and is always served as an attachment. Answers 404 when the message has no attachment, when the transport reported a file it does not serve, or when it no longer holds it.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/messages/:id/media \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

React to a message

API key · messages:write

Sets this number's reaction on a message it sent or received; an empty emoji removes it. Works on any message that has reached WhatsApp.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/messages/:id/reactions \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emoji": "\ud83d\udc4d"
  }'

Responses

Mark a message read

API key · messages:write

Shows blue ticks to the sender of an inbound message. Idempotent: a second call sends nothing.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/messages/:id/read \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Move a scheduled message

API key · messages:write

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/messages/:id/reschedule \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "send_at": "2026-10-01T09:00:00Z",
    "timezone": "Europe/London"
  }'

Responses

Delete a message for everyone

API key · messages:write

Removes a message this number sent from every phone in the chat, within WhatsApp's window of about two and a half days. The record stays in ChatRail, marked deleted, and the deletion is audited.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/messages/:id/revoke \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Check whether a number is on WhatsApp

API key · messages:read

Answers checked: false when the engine cannot say. Treat that as "send anyway": refusing a message because a check failed turns a missing provider feature into a delivery failure. chat_id is WhatsApp's own id for the chat when it gives one. An answer from the last 24 hours is reused (cached: true) without asking WhatsApp again. Lookups that do reach WhatsApp go through your connected number and are limited to 10 a minute per workspace, and 30 a day on Sandbox.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/numbers/check \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Check up to 10 numbers

API key · messages:read

The same check for several numbers. Each gets its own line in results, in the order sent: a number that cannot be parsed has reason: invalid_number, and numbers a spent budget could not reach have reason: minute_limit or daily_limit instead of failing the request. Repeats in one request are looked up once.

Body

Request

curl -X POST https://www.chatrail.dev/v1/numbers/check \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": "main",
    "phones": [
      "+923001234567",
      "+2348031234567"
    ]
  }'

Responses

List connections

API key · connections:read

Request

curl -X GET https://www.chatrail.dev/v1/connections \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Create a connection

API key · connections:write

Returns callback_token exactly once. It cannot be retrieved again; store it when you receive it. On the Team plan, add proxy to link this number through its own HTTP proxy instead of ChatRail's address: server is an IP address and port (not a hostname, and a public address), with an optional username and password that are stored encrypted and never returned. Use a fixed address, ideally in the same country as the number.

Body

Request

curl -X POST https://www.chatrail.dev/v1/connections \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "operations",
    "name": "Operations line"
  }'

Responses

Get a connection

API key · connections:read

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/connections/:connection \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Change connection settings

API key · connections:write

Send only the settings you want to change. reject_calls declines incoming calls on this number automatically. It is off by default, because the caller sees the call declined. Each call is still announced as call.received, with rejected saying whether it was declined. proxy routes this number through its own HTTP proxy (Team plan), or removes it with null (any plan). A proxy is server (an IP address and port, not a hostname, and a public address) with an optional username and password. It is applied when the number is paired, so it can only be changed before the number is linked, or after WhatsApp has logged it out. The response shows the address and has_credentials; the username and password are never returned.

Parameters

Body

Request

curl -X PATCH https://www.chatrail.dev/v1/connections/:connection \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reject_calls": true
  }'

Responses

Delete a connection

API key · connections:write

Soft deletes it and queues removal of its data.

Parameters

Request

curl -X DELETE https://www.chatrail.dev/v1/connections/:connection \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

List WhatsApp groups

API key · connections:read

Returns a bounded, name-sorted page for a group picker. Group ids use the same from.group representation delivered in message webhooks. Participant identities are never returned.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/connections/:connection/groups \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Begin pairing

API key · connections:write

Issues a short-lived, single-use grant. By default it holds a QR; with {"method": "code", "phone": "+447700900123"} it holds a pairing code instead, which the person enters under Linked devices → Link with phone number (encoding pairing-code). Either is fetched once with the grant id: each is a pairing credential, so whoever uses it links *their* device to the number.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/pair \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "code",
    "phone": "+447700900123"
  }'

Responses

Redeem a QR grant

API key · connections:write

Single use. A redeemed or expired grant is gone; ask for another.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/connections/:connection/qr/:grantId \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Resume a suspended connection

API key · connections:write

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/resume \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Suspend a connection

API key · connections:write

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/suspend \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Create a group

API key · connections:write

Creates a WhatsApp group with this number as its owner. Everyone added counts against the member-add guardrail: at most 20 people per connection per hour, because adding people who did not ask to be added is how numbers get reported. Paid plans.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/groups \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Riverside viewings",
    "participants": [
      "+447700900123",
      "+447700900456"
    ]
  }'

Responses

Get a group

API key · connections:read

Name, description, settings and members with their roles.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/connections/:connection/groups/:group \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Update a group

API key · connections:write

Change the name or description, or who may send messages and edit group info. This number must be an admin of the group. Paid plans.

Parameters

Body

Request

curl -X PATCH https://www.chatrail.dev/v1/connections/:connection/groups/:group \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages_admins_only": true
  }'

Responses

Get a group invite link

API key · connections:read

The chat.whatsapp.com link for joining the group.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/connections/:connection/groups/:group/invite \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Revoke a group invite link

API key · connections:write

Invalidates the current link and returns a new one.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/groups/:group/invite/revoke \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Leave a group

API key · connections:write

This number leaves the group.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/groups/:group/leave \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Change group members

API key · connections:write

add, remove, promote to admin or demote. Adding counts against the member-add guardrail (20 per connection per hour). Paid plans.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/connections/:connection/groups/:group/participants \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "participants": [
      "+447700900789"
    ]
  }'

Responses

List schedules

API key · schedules:read

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/schedules \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Create a recurring schedule

API key · schedules:write

Daily, weekly or monthly, resolved in the given IANA timezone. A schedule that fell behind fires once and drops the backlog rather than delivering days of stale messages.

Body

Request

curl -X POST https://www.chatrail.dev/v1/schedules \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Friday digest",
    "timezone": "Europe/London",
    "recurrence": {
      "type": "weekly",
      "hour": 9,
      "minute": 0,
      "days_of_week": [
        5
      ]
    },
    "message": {
      "connection": "main",
      "to": "+15551234567",
      "body": "Your weekly digest is ready."
    }
  }'

Responses

Get a schedule

API key · schedules:read

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/schedules/:id \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Cancel a schedule

API key · schedules:write

Permanent. A cancelled schedule cannot be restarted.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/schedules/:id/cancel \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Pause a schedule

API key · schedules:write

Keeps the schedule and stops it firing.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/schedules/:id/pause \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Resume a schedule

API key · schedules:write

The next run is computed from now. A schedule paused for a month does not fire the month it missed.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/schedules/:id/resume \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

List webhook endpoints

API key · webhooks:read

Request

curl -X GET https://www.chatrail.dev/v1/webhook-endpoints \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Register a webhook endpoint

API key · webhooks:write

Returns the signing secret exactly once. Every delivery is signed with HMAC-SHA256 over the timestamp, a period, and the raw request body; verify it and reject stale timestamps. The URL is validated at registration and the connection pinned at delivery, so an endpoint pointing at a private address is refused. Works with an API key holding webhooks:write, so a deploy script can register its own endpoint; every change is audited.

Body

Request

curl -X POST https://www.chatrail.dev/v1/webhook-endpoints \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/chatrail",
    "events": [
      "message.received",
      "message.delivered",
      "message.failed"
    ],
    "description": "Order updates"
  }'

Responses

Delete a webhook endpoint

API key · webhooks:write

Parameters

Request

curl -X DELETE https://www.chatrail.dev/v1/webhook-endpoints/:id \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Re-enable a webhook endpoint

API key · webhooks:write

Turns back on an endpoint that was disabled after 50 failed deliveries in a row. The failure count restarts at zero and the signing secret is unchanged. Events skipped while it was disabled are not re-sent.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/webhook-endpoints/:id/enable \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

List people who must not be messaged

API key · messages:read

Numbers on the workspace's opt-out list, oldest first. A number gets here two ways: the person wrote a stop word such as "STOP" in a direct chat (source: inbound_keyword), or you added it (source: api). Sends to a number on the list are refused with RECIPIENT_OPTED_OUT, and so are messages already queued or scheduled for it.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/opt-outs \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Add a number to the opt-out list

API key · messages:write

For someone who has asked you, outside WhatsApp, to stop. Adding a number that is already on the list succeeds and changes nothing. Sending to it is refused from then on, including anything already queued or scheduled.

Body

Request

curl -X POST https://www.chatrail.dev/v1/opt-outs \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+447700900123"
  }'

Responses

Remove a number from the opt-out list

API key · messages:write

Only for a person who has asked to hear from you again. If they write a stop word again they are opted out again.

Parameters

Request

curl -X DELETE https://www.chatrail.dev/v1/opt-outs/:phone \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

List credentials

API key · ai:read

Fingerprints and metadata only; the key itself is never returned.

Request

curl -X GET https://www.chatrail.dev/v1/ai/credentials \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Store a model provider credential

API key · ai:write

Encrypted at rest and never returned. AI is off by default and enabled per connection.

Body

Request

curl -X POST https://www.chatrail.dev/v1/ai/credentials \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "label": "Production key",
    "api_key": "sk-ant-replace-with-your-own-key"
  }'

Responses

Delete a credential

API key · ai:write

Parameters

Request

curl -X DELETE https://www.chatrail.dev/v1/ai/credentials/:id \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Test a credential

API key · ai:write

Makes one small call to the model provider with this credential and the given model, so a wrong key or model name shows up before a customer is waiting on a reply.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/ai/credentials/:id/test \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna"
  }'

Responses

Get the AI policy for a connection

API key · ai:read

Absent policy means AI is off for that connection, which is the default.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/ai/policies/:connection \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Set the AI policy for a connection

API key · ai:write

Draft or auto mode, with token, rate and monthly cost ceilings. Absent policy means AI is off for that connection.

Parameters

Body

Request

curl -X PUT https://www.chatrail.dev/v1/ai/policies/:connection \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "019bf4a1-0000-7000-8000-000000000000",
    "enabled": true,
    "mode": "draft",
    "model": "claude-sonnet-4-5",
    "system_instruction": "Answer only from the attached context. If the answer is not there, say so."
  }'

Responses

Summarise what happened to AI drafts

API key · ai:read

Counts only, never text: drafts sent unchanged, sent after editing, or dismissed and why; runs that ran with no business context at all; and correlation corrections grouped by the rule that originally fired. Accepts days (default 30).

Request

curl -X GET https://www.chatrail.dev/v1/ai/quality \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

List AI runs

API key · ai:read

Usage, cost, outcome and the proposed reply. The assembled prompt is represented by its hash and the list of context keys that went into it, never reproduced.

Request

curl -X GET https://www.chatrail.dev/v1/ai/runs \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Dismiss an AI draft

API key · ai:write

Removes a pending draft from the human review queue without sending it. Supply a reason where you know it: the counts are what make draft quality measurable, and wrong_correlation in particular is the only signal that a reply was matched to the wrong alert.

Parameters

Body

Request

curl -X POST https://www.chatrail.dev/v1/ai/runs/:id/dismiss \
  -H "Authorization: Bearer $CHATRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "wrong_context"
  }'

Responses

Send an AI draft

API key · ai:write

Accepts the pending draft through the normal durable message outbox.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/ai/runs/:id/send \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

List members and pending invitations

Dashboard session

Request

curl -X GET https://www.chatrail.dev/v1/members

Responses

Accept an invitation

Dashboard session

Requires a signed-in session whose address matches the invited one. Possessing the token is not enough — a forwarded invitation email must not be a way into a workspace.

Body

Request

curl -X POST https://www.chatrail.dev/v1/members/accept \
  -H "Content-Type: application/json" \
  -d '{
    "token": "the token from the invitation link"
  }'

Responses

Invite somebody

Dashboard session

Emails a single-use link bound to that address. The token is never returned in the response. Nobody may invite to a role above their own.

Body

Request

curl -X POST https://www.chatrail.dev/v1/members/invitations \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@company.com",
    "role": "viewer"
  }'

Responses

Revoke an invitation

Dashboard session

Parameters

Request

curl -X DELETE https://www.chatrail.dev/v1/members/invitations/:id

Responses

Resend an invitation

Dashboard session

Emails the invitation again with a fresh link. Dashboard only.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/members/invitations/:id/resend

Responses

Change a member's role

Dashboard session

Parameters

Body

Request

curl -X PATCH https://www.chatrail.dev/v1/members/:id \
  -H "Content-Type: application/json" \
  -d '{
    "role": "developer"
  }'

Responses

Remove a member

Dashboard session

Parameters

Request

curl -X DELETE https://www.chatrail.dev/v1/members/:id

Responses

List API keys

Dashboard session

Request

curl -X GET https://www.chatrail.dev/v1/api-keys

Responses

Issue an API key

Dashboard session

Returns the key exactly once. It is stored only as a hash and cannot be recovered. A key may never hold more than the person issuing it.

Body

Request

curl -X POST https://www.chatrail.dev/v1/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order service",
    "scopes": [
      "messages:write",
      "messages:read"
    ],
    "environment": "live"
  }'

Responses

Revoke an API key

Dashboard session

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/api-keys/:id/revoke

Responses

Rotate an API key

Dashboard session

Issues a replacement and revokes the old one.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/api-keys/:id/rotate

Responses

Usage counts

API key · usage:read

Counts only. A count of messages is not a message; no content is reachable here.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/usage \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Confirm a credential

API key

Shows exactly what the presented credential can do. The first call to make.

Request

curl -X GET https://www.chatrail.dev/v1/whoami \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Get the current workspace

Dashboard session

Includes the plan and what has been used against it.

Request

curl -X GET https://www.chatrail.dev/v1/workspace

Responses

Rename the workspace

Dashboard session

Changes the display name shown to members, on invitations and in emails. The slug does not change. Needs workspace:update.

Body

Request

curl -X PATCH https://www.chatrail.dev/v1/workspace \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kettle & Co"
  }'

Responses

Get the billing account

Dashboard session

What Creem says about this workspace: customer, subscription, status and the current period. Distinct from the plan on /v1/workspace, which is what the workspace is actually entitled to and is never blocked on this being reachable.

Request

curl -X GET https://www.chatrail.dev/v1/billing

Responses

Start a checkout

Dashboard session

Returns a Creem-hosted checkout URL for the chosen paid plan. When the workspace has a paired number from a regional-pricing country, the checkout opens with that discount.

Body

Request

curl -X POST https://www.chatrail.dev/v1/billing/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "core_ai",
    "return_path": "/settings/billing"
  }'

Responses

Crypto payment options

Dashboard session

Whether crypto checkout is available, the accepted coins, the prepaid price of each plan for 3 and 12 months (12 months costs 10), and this workspace's prepaid period and newest unpaid order, if any. A crypto purchase is a prepaid block of months, not a subscription: a wallet cannot be charged again automatically. With a regional price, price_usd is the reduced price, list_price_usd the full one, and regional names the discount.

Request

curl -X GET https://www.chatrail.dev/v1/billing/crypto

Responses

Start a crypto checkout

Dashboard session

Creates a NOWPayments invoice for a prepaid period and returns its URL. The plan is applied when NOWPayments reports the payment finished. Buying the same plan again extends the running period; a different plan, or a workspace paying by card, is refused.

Body

Request

curl -X POST https://www.chatrail.dev/v1/billing/crypto/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "core_ai",
    "months": 12,
    "pay_currency": "usdttrc20",
    "return_path": "/dashboard/billing"
  }'

Responses

Check whether a plan change is possible

Dashboard session

Whether moving to the given plan is allowed, and if not, how many connected numbers would have to be disconnected first. A downgrade is refused rather than applied when it would strand a number over the target plan's limit, because the alternatives are a silently suspended number — whose linked device stops working and needs a QR re-scan — and a customer permanently exceeding the plan they pay for. Changes nothing and spends nothing, so it needs only billing:read.

Body

Request

curl -X POST https://www.chatrail.dev/v1/billing/plan-change-check \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "core"
  }'

Responses

List paid plans

Dashboard session

The plans a checkout can be started for, with the price. purchasable is false when the plan has no Creem product configured yet. regional gives the plan's monthly price for workspaces that paired a WhatsApp number from a country with regional pricing. Before any number is paired it can be shown from the visitor's location with requires_number: true, meaning it applies only once a number from that country is paired. Null otherwise.

Request

curl -X GET https://www.chatrail.dev/v1/billing/plans

Responses

Open the customer portal

Dashboard session

A Creem-hosted page to update payment details or cancel — self-serve.

Request

curl -X POST https://www.chatrail.dev/v1/billing/portal

Responses

The visitor's regional prices

No credential

For the public pricing pages: the regional monthly price of each plan in a country (?country=NG, else the visitor's location), or regional: null when there is none. It only shows the price; a workspace pays it once it pairs a WhatsApp number from that country.

Request

curl -X GET https://www.chatrail.dev/v1/billing/regional-price

Responses

End the session

Dashboard session

Request

curl -X POST https://www.chatrail.dev/v1/auth/logout

Responses

Finish a Google or GitHub sign-in

No credential

Where the provider sends the person back. Only an address the provider has verified is accepted; it lands in the same account an emailed code for that address would. Always redirects to the sign-in page — with a session cookie on success, or auth_error on failure.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/auth/oauth/:provider/callback

Responses

Start a Google or GitHub sign-in

No credential

A browser navigation, not an API call: redirects to the provider with a state value and a PKCE challenge held in a short-lived HttpOnly cookie. An optional same-origin next path is where the person lands afterwards.

Parameters

Request

curl -X GET https://www.chatrail.dev/v1/auth/oauth/:provider/start

Responses

List sign-in providers

No credential

Which of Google and GitHub are switched on for this deployment, so a sign-in page only offers buttons that will work.

Request

curl -X GET https://www.chatrail.dev/v1/auth/providers

Responses

Request a sign-in code

No credential

Always answers 202, whether or not the address has an account. It is not an existence check and must not be presented as one.

Body

Request

curl -X POST https://www.chatrail.dev/v1/auth/request-code \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com"
  }'

Responses

Read the current session

Dashboard session

Request

curl -X GET https://www.chatrail.dev/v1/auth/session

Responses

Exchange a code for a session

No credential

Every failure returns the same error — no code, wrong code, expired, too many attempts. Distinguishing them would reintroduce an oracle.

Body

Request

curl -X POST https://www.chatrail.dev/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "code": "123456"
  }'

Responses

Read the signed-in profile

Dashboard session

Request

curl -X GET https://www.chatrail.dev/v1/profile

Responses

Update the display name

Dashboard session

Body

Request

curl -X PATCH https://www.chatrail.dev/v1/profile \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace"
  }'

Responses

Record how you heard about ChatRail

Dashboard session

Asked once on the getting-started page. skipped records a dismissal so the question is not shown again. Answering again replaces the answer.

Body

Request

curl -X PUT https://www.chatrail.dev/v1/profile/heard-from \
  -H "Content-Type: application/json" \
  -d '{
    "source": "linkedin",
    "detail": "A post about WhatsApp bots"
  }'

Responses

Read notification preferences

Dashboard session

Request

curl -X GET https://www.chatrail.dev/v1/profile/notification-preferences

Responses

Update notification preferences

Dashboard session

Body

Request

curl -X PATCH https://www.chatrail.dev/v1/profile/notification-preferences \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryProblems": false,
    "aiLimits": true
  }'

Responses

List active account sessions

Dashboard session

Lists only the signed-in user’s live sessions and never exposes session tokens.

Request

curl -X GET https://www.chatrail.dev/v1/profile/sessions

Responses

Sign out other devices

Dashboard session

Request

curl -X POST https://www.chatrail.dev/v1/profile/sessions/revoke-others

Responses

Sign out a device

Dashboard session

A session belonging to another user is reported as not found.

Parameters

Request

curl -X DELETE https://www.chatrail.dev/v1/profile/sessions/:sessionId

Responses

MCP endpoint

API key · mcp:read

Model Context Protocol over a stateless streamable HTTP transport. OAuth 2.1 access tokens and workspace API keys are both accepted. Read-only by default; mutating tools preview and apply only when called again with confirm: true. No tool returns message content.

Request

curl -X POST https://www.chatrail.dev/v1/mcp \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

List MCP tools

API key

Available to dashboard sessions for setup and to API keys with mcp:read.

Request

curl -X GET https://www.chatrail.dev/v1/mcp/tools \
  -H "Authorization: Bearer $CHATRAIL_API_KEY"

Responses

Liveness

No credential

Never checks dependencies. Point a restart policy here, not a traffic probe.

Request

curl -X GET https://www.chatrail.dev/healthz

Responses

Worker liveness

No credential

Whether the background worker has recorded a heartbeat in the last five minutes. For an external uptime monitor: the worker runs the other alerts, so it cannot report its own death.

Request

curl -X GET https://www.chatrail.dev/healthz/worker

Responses

Prometheus metrics

No credential

Not registered unless METRICS_TOKEN is configured. No label carries a workspace, connection, number or session name.

Request

curl -X GET https://www.chatrail.dev/metrics

Responses

Readiness

No credential

Checks dependencies. Point the load balancer here.

Request

curl -X GET https://www.chatrail.dev/readyz

Responses

This document

No credential

Request

curl -X GET https://www.chatrail.dev/v1/openapi.json

Responses

Creem webhook

No credential

Called by Creem, not by you. Verified against creem-signature, a plain HMAC-SHA256 of the exact request body — Creem retries a non-2xx for up to 24 hours, so redeliveries are expected and deduplicated by event id.

Request

curl -X POST https://www.chatrail.dev/v1/billing/creem/webhook

Responses

NOWPayments payment notification

No credential

Called by NOWPayments, not by you. Verified against x-nowpayments-sig, an HMAC-SHA512 of the key-sorted JSON body. Repeated notifications are deduplicated by payment id and status.

Request

curl -X POST https://www.chatrail.dev/v1/billing/nowpayments/webhook

Responses

Signed provider callback

No credential

Called by the WhatsApp transport, not by you. The URL names the session; the body is signed with the connection’s own key (X-Webhook-Hmac, HMAC-SHA512 over the exact bytes). Replaces the token URL, which put a credential in every proxy log.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/provider/:providerName/sessions/:sessionId

Responses

Provider callback

No credential

Called by the WhatsApp transport, not by you. Authenticated by the per-connection token returned once when the connection was created. Redeliveries are deduplicated.

Parameters

Request

curl -X POST https://www.chatrail.dev/v1/provider/:providerName/:token

Responses