Public API Reference

Endpoints, scopes, and examples for tickets, messages, and actions.

Use scoped API keys to manage omnichannel tickets and actions from your systems.

Base URL

All requests go through the public gateway.

https://api.threada.ai

Authentication

Send the API key in the `X-Api-Key` header.
Create and rotate keys in Admin → API keys; use one key per integration.
Keys are tenant-scoped and enforce least-privilege scopes.

Scopes

`support.read` — list and retrieve tickets, messages, and actions.
`support.write` — create/update tickets and append messages.
`support.actions` — execute actions and query action status.

Pagination

List endpoints accept `limit` and `page_token`.
Pass the `next_page_token` value into the next request.

Errors

Errors return `{ error: { type, message, code } }`.
HTTP status codes mirror the `code` value.

Request & response examples

List tickets

Fetch open tickets across all channels.

Request

curl -X GET "https://api.threada.ai/api/v1/public/tickets?limit=25" \
  -H "X-Api-Key: YOUR_API_KEY"

Response

{
  "items": [
    {
      "ticket_id": "TICKET_ID",
      "tenant_id": "TENANT_ID",
      "subject": "SUBJECT",
      "status": "open",
      "priority": "normal",
      "channel": "email",
      "tags": ["vip", "returns"],
      "last_message_at": "2026-02-04T18:32:11Z"
    }
  ],
  "next_page_token": "NEXT_PAGE_TOKEN"
}

Create a ticket

Open a new ticket with an initial message.

Request

curl -X POST "https://api.threada.ai/api/v1/public/tickets" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "SUBJECT",
    "priority": "normal",
    "channel": "email",
    "contact": {
      "name": "CUSTOMER_NAME",
      "email": "customer@example.com"
    },
    "tags": ["returns"],
    "initial_message": {
      "role": "user",
      "content": "MESSAGE_BODY",
      "external_message_id": "EXT_MSG_ID"
    }
  }'

Response

{
  "ticket": {
    "summary": {
      "ticket_id": "TICKET_ID",
      "tenant_id": "TENANT_ID",
      "subject": "SUBJECT",
      "status": "open",
      "priority": "normal",
      "channel": "email",
      "tags": ["returns"],
      "created_at": "2026-02-04T18:32:11Z"
    },
    "contact": {
      "name": "CUSTOMER_NAME",
      "email": "customer@example.com"
    },
    "messages": [
      {
        "message_id": "MESSAGE_ID",
        "role": "user",
        "content": "MESSAGE_BODY",
        "channel": "email",
        "created_at": "2026-02-04T18:32:11Z"
      }
    ]
  }
}

Execute an action

Trigger a custom HTTP automation for a ticket.

Request

curl -X POST "https://api.threada.ai/api/v1/public/tickets/TICKET_ID/actions" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "type": "custom_http",
      "method": "POST",
      "url": "/hooks/zapier",
      "headers": {
        "X-Source": "threada"
      },
      "body_json": "{\"event\":\"ticket_updated\"}"
    }
  }'

Response

{
  "action": {
    "action_id": "ACTION_ID",
    "tenant_id": "TENANT_ID",
    "ticket_id": "TICKET_ID",
    "action_type": "custom_http",
    "status": "succeeded",
    "requested_by": "api_key:API_KEY_ID",
    "payload": {
      "type": "custom_http",
      "method": "POST",
      "url": "/hooks/zapier",
      "headers": {
        "X-Source": "threada"
      },
      "body_json": "{\"event\":\"ticket_updated\"}"
    }
  }
}

Need more endpoints?

Contact sales