REST API Reference

API Reference

The CrownSync Playbooks REST API provides programmatic access to incidents, playbooks, and platform data. All API requests must be authenticated with a Bearer token (API key) and use HTTPS. The base URL for all endpoints is https://pb.crownsync.uk/api/v1.

Authentication

All API requests require a valid API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are created and managed from Admin → Integrations → API Keys. Each key has specific permissions that determine which endpoints it can access.

Rate Limits

The API enforces rate limits to ensure fair usage:

• 100 requests per minute per API key for standard endpoints
• 10 requests per minute per API key for incident creation

When a rate limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating when to retry.

Endpoints

GET /health

Returns the API health status. Does not require authentication. Useful for monitoring integrations.

GET /playbooks

Returns a list of all active playbooks for your organisation. Requires the Read playbooks permission.

POST /incidents

Creates a new incident. Requires the Create incidents permission. The request body must include:

• title (string, required) — Incident title
• severity (string, required) — One of: critical, high, medium, low
• description (string, optional) — Incident description
• category (string, optional) — Incident category slug
• playbookSlug (string, optional) — Associated playbook

GET /incidents

Returns a list of incidents for your organisation. Supports query parameters for filtering by status, severity, and date range. Requires the Read incidents permission.

GET /incidents/:id

Returns the full details of a specific incident, including its timeline, severity, status, and metadata. Requires the Read incidents permission.

PATCH /incidents/:id

Updates an existing incident. Supports partial updates — only include the fields you want to change. Requires the Update incidents permission.

POST /incidents/:id/log

Adds an action log entry to an incident's timeline. Requires the Log actions permission. The request body must include:

• action (string, required) — Description of the action taken
• performedBy (string, optional) — Name of the person who performed the action
• timestamp (string, optional) — ISO 8601 timestamp (defaults to current time)

Example Requests

Create an incident using curl:

curl -X POST https://pb.crownsync.uk/api/v1/incidents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Suspected ransomware infection",
    "severity": "critical",
    "description": "Multiple endpoints reporting encrypted files",
    "category": "ransomware-infection"
  }'

Log an action to an incident:

curl -X POST https://pb.crownsync.uk/api/v1/incidents/inc_abc123/log \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Isolated affected workstations from the network",
    "performedBy": "Jane Smith"
  }'

Error Codes

Webhook Verification (HMAC-SHA256)

Outbound webhooks from CrownSync include an X-CrownSync-Signature header. To verify a webhook payload:

1. Retrieve the raw request body as a string (do not parse the JSON first)
2. Compute an HMAC-SHA256 hash of the raw body using your webhook signing secret as the key
3. Hex-encode the result and compare it to the value in the X-CrownSync-Signature header
4. If the values match, the payload is authentic. If they do not match, reject the request.