API Reference

FairDesk API.

REST API. Auth with a Bearer token.

Base URL

https://api.faircompany.ai/v1/desk

Authentication

All requests use a Bearer token. Get one from fairdesk.ai/app.

Authorization: Bearer fair_live_...

Endpoints

POST/v1/desk/tickets

Create a new ticket.

{
  "input": "...",
  "metadata": { "ref": "your-internal-id" }
}
{
  "id": "ticket_01HX...",
  "status": "queued"
}

GET/v1/desk/tickets/:id

Fetch a ticket by ID. Returns full state.

GET/v1/desk/tickets

List tickets. Supports cursor pagination, created_after, status, and metadata filters.

DELETE/v1/desk/tickets/:id

Cancel a queued ticket.

POST/v1/desk/webhooks

Register a webhook for ticket.created, ticket.completed, ticket.failed events. Signed with HMAC-SHA256.

Errors

  • 401 Unauthorized — missing or invalid Bearer token.
  • 422 Unprocessable — input failed validation.
  • 429 Rate Limit — exponential backoff with the Retry-After header.

SDKs

Typed clients available for TypeScript / Python via @fair/sdk (npm) and fair-sdk (PyPI). Full OpenAPI spec at api.faircompany.ai/openapi.