API reference (OpenAPI 3.1)

AskAIs Customer Service ships a complete OpenAPI 3.1 spec describing every public endpoint. It powers our auto-generated SDKs and works with any tool in the OpenAPI ecosystem (Insomnia, Postman, Swagger UI, Hoppscotch, etc.).

Get the spec

# Live (cached 5 min, CORS open)
curl https://cs.askais.com/api/v1/openapi.json

# Save to disk
curl https://cs.askais.com/api/v1/openapi.json -o singlink-openapi.json

Base URL

• Cloud: https://cs.askais.com/api/v1
• Self-host: whatever your APP_URL resolves to, suffixed with /api/v1

Authentication

Two schemes, both via Authorization: Bearer <value>:

• Contact JWT — issued by POST /auth/identify. Scoped to a single contact. Used by web / mobile SDKs.
• Workspace API key — sk_live_..., generated in Settings → API Keys. Scoped to the whole workspace. For server-to-server.

Endpoints at a glance

• POST /auth/identify — issue a contact JWT
• POST /conversations — start a new chat
• GET /conversations — list yours
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload — get a presigned S3 POST URL
• POST /upload/{id}/confirm

Errors

All non-2xx responses use a stable envelope:

{
  "error": {
    "code": "validation_error",
    "message": "content or attachments required",
    "field": "content"
  }
}

Codes: validation_error, unauthorized, forbidden, not_found, conflict, unprocessable, rate_limit_exceeded, internal_error.

Real-time companion

REST is fine for one-shot calls. For live messages, connect to wss://<wsUrl>/v1/ws?token=<jwt> and listen for message:new, ai:stream:delta, ai:stream:end, typing, and presence events. See Web widget for the full event schema.