Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
openapi: 3.2.0
info:
title: ChatRail Workspace API
version: 1.0.0
description: 'Send, schedule and receive WhatsApp messages through a linked-device session.
**Two things the API is careful about, which shape every endpoint below.**
*Accepted is not delivered.* A 202 means the message is durably stored and queued. Only the `status` field ever claims WhatsApp delivered anything, and `queued`, `submitted`, `sent`, `delivered` and `read` are deliberately distinct.
*A retry must not send twice.* Send `Idempotency-Key` on every send. A replay returns the original response; a concurrent duplicate is told to retry rather than allowed to race.'
contact:
name: ChatRail
url: https://www.chatrail.dev
servers:
- url: https://www.chatrail.dev
security:
- apiKey: []
tags:
- name: Workspace
description: Identity, credentials, plan and usage.
paths:
/v1/whoami:
get:
summary: Confirm a credential
description: Shows exactly what the presented credential can do. The first call to make.
tags:
- Workspace
operationId: get_v1_whoami
responses:
'200':
description: The principal, its scopes and its workspace.
security:
- apiKey: []
/v1/workspace:
get:
summary: Get the current workspace
description: Includes the plan and what has been used against it.
tags:
- Workspace
operationId: get_v1_workspace
responses:
'200':
description: The workspace, the caller role and the plan.
security:
- session: []
patch:
summary: Rename the workspace
description: Changes the display name shown to members, on invitations and in emails. The slug does not change. Needs `workspace:update`.
tags:
- Workspace
operationId: patch_v1_workspace
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
required:
- name
additionalProperties: false
example:
name: Kettle & Co
responses:
'200':
description: The workspace id, slug and new name.
'400':
description: The name is empty or longer than 80 characters.
security:
- session: []
/v1/usage:
get:
summary: Usage counts
description: Counts only. A count of messages is not a message; no content is reachable here.
tags:
- Workspace
operationId: get_v1_usage
parameters:
- name: days
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 365
responses:
'200':
description: Aggregated counts for the workspace.
security:
- apiKey:
- usage:read
- session: []
x-scopes:
- usage:read
/v1/api-keys:
post:
summary: Issue an API key
description: 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.
tags:
- Workspace
operationId: post_v1_api-keys
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 80
scopes:
minItems: 1
type: array
items:
type: string
enum:
- messages:read
- messages:write
- connections:read
- connections:write
- webhooks:read
- webhooks:write
- schedules:read
- schedules:write
- ai:read
- ai:write
- mcp:read
- mcp:write
- usage:read
environment:
default: live
type: string
enum:
- live
- test
required:
- name
- scopes
additionalProperties: false
example:
name: Order service
scopes:
- messages:write
- messages:read
environment: live
responses:
'201':
description: The key, once.
'403':
description: Your role cannot grant those scopes.
security:
- session: []
get:
summary: List API keys
tags:
- Workspace
operationId: get_v1_api-keys
responses:
'200':
description: Key metadata and prefixes, never the keys.
security:
- session: []
/v1/api-keys/{id}/revoke:
post:
summary: Revoke an API key
tags:
- Workspace
operationId: post_v1_api-keys__id__revoke
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Key id.
responses:
'200':
description: Revoked, immediately.
'404':
description: No such key.
security:
- session: []
/v1/api-keys/{id}/rotate:
post:
summary: Rotate an API key
description: Issues a replacement and revokes the old one.
tags:
- Workspace
operationId: post_v1_api-keys__id__rotate
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Key id.
responses:
'200':
description: The new key, once.
'404':
description: No such key.
security:
- session: []
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
description: 'A workspace API key, `cr_live_…`. Server-side only: it carries workspace authority and must never reach a browser.'
session:
type: apiKey
in: cookie
name: chatrail_session
description: Dashboard session cookie. Set by `/v1/auth/verify`.