API reference | SquawkDesk

Authentication

Authorization: Bearer sdk_your_key_here

Base URL: https://squawkdesk.app/api/v1. Keys carry scopes: tickets:read, tickets:write, contacts:read, contacts:write. Errors return {"error": "message"} with a 4xx or 5xx status.

Tickets

Method	Path	Notes
GET	/tickets	Query: status (comma list), priority, assignee_id, group_id, requester_email, tag, updated_since (ISO), search, page, per_page (max 200).
GET	/tickets/:number	Number or UUID. Returns ticket, requester, messages, attachments.
POST	/tickets	Body: subject, requester_email, body_html or body_text, requester_name, priority, type, group_id, assignee_id, mailbox_id, cc[], tags[], custom_fields{}.
PATCH	/tickets/:number	Any of subject, status, priority, type, assignee_id, group_id, tags, custom_fields, due_at, requester_email.
POST	/tickets/:number/replies	Body: body_html or body_text, kind (reply or note), agent_email (attribute to an agent), status (set after reply).
DELETE	/tickets/:number	Moves to trash.

curl -X POST https://squawkdesk.app/api/v1/tickets \
  -H "Authorization: Bearer sdk_xxx" -H "Content-Type: application/json" \
  -d '{"subject":"Server down","requester_email":"[email protected]","body_text":"Primary DC is unreachable","priority":"urgent","tags":["monitoring"]}'

Statuses: open, pending, on_hold, resolved, closed. Priorities: low, normal, high, urgent.

Contacts and companies

Method	Path	Notes
GET	/contacts	Query: email, search, page, per_page.
GET	/contacts/:id
POST	/contacts	Body: email (required), name, phone, company_id, custom_fields. Upserts by email.
GET	/companies
POST	/companies	Body: name (required), domains[], custom_fields. Upserts by name.

Reference

GET	/me	Tenant and key scopes.
GET	/agents
GET	/groups
GET	/articles	Published articles. Query: search.

Webhooks

Configure endpoints under Settings. Each delivery is a POST with headers X-SquawkDesk-Event and X-SquawkDesk-Signature (hex HMAC-SHA256 of the raw body using the endpoint secret). Respond 2xx within 10 seconds. Failed deliveries retry with backoff for up to 8 attempts.

Events: ticket.created, ticket.updated (includes changes), ticket.replied (includes message), ticket.resolved, ticket.sla_breached, and automation.* from the "fire webhook" action.

{"event":"ticket.created","at":"2026-10-16T18:20:11.000Z","ticket":{"id":"...","number":1042,"subject":"Server down","status":"open","priority":"urgent", ...}}

Verifying a signature (Node)

const sig = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (sig !== req.get('x-squawkdesk-signature')) return res.status(401).end();

Inbound email relay

If you run your own mail relay, you can POST raw RFC 822 messages for forwarding-type mailboxes to /inbound/mail with header X-Inbound-Token. This endpoint is for platform operators; customers should use Microsoft 365, Google, IMAP or forwarding instead.