API Documentation

All API requests must include a valid API key in the Authorization header using the Bearer scheme. API keys are scoped to a single space and are available on the Business plan.

Authorization: Bearer rqp_a1b2c3d4e5f6...

How to get an API key

1. Navigate to your space settings
2. Open the "API Keys" tab
3. Click "Create API Key" and give it a descriptive name
4. Copy the key immediately — it will not be shown again

Create a new request in the space associated with the API key.

Request Body

{
  "templateId": "tpl_abc123",
  "fields": [
    { "fieldId": "field_1", "value": "Server is down" },
    { "fieldId": "field_2", "value": "high" }
  ],
  "priority": "high",
  "assignedToId": "user_xyz"
}

Response 201

{
  "data": {
    "id": "req_def456",
    "status": "todo",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Error Responses

• 401 — Invalid or missing API key
• 403 — Template does not belong to this space
• 422 — Missing required template fields or invalid data
• 429 — Rate limit exceeded

Retrieve a paginated list of requests in the space. Supports filtering by status, template, assignee, and date range.

Query Parameters

Response 200

{
  "data": [
    {
      "id": "req_def456",
      "templateId": "tpl_abc123",
      "status": "in_progress",
      "priority": "high",
      "assignedToId": "user_xyz",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T11:00:00.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

Retrieve the full details of a single request, including all field values.

Response 200

{
  "data": {
    "id": "req_def456",
    "templateId": "tpl_abc123",
    "status": "in_progress",
    "priority": "high",
    "assignedToId": "user_xyz",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T11:00:00.000Z",
    "fieldValues": [
      { "fieldId": "field_1", "name": "Description", "value": "Server is down" },
      { "fieldId": "field_2", "name": "Category", "value": "high" }
    ]
  }
}

Error Responses

• 401 — Invalid or missing API key
• 404 — Request not found or belongs to a different space
• 429 — Rate limit exceeded

Update the status of an existing request. Only valid status transitions are accepted.

Request Body

{
  "status": "in_progress"
}

Valid Status Transitions

Response 200

{
  "data": {
    "id": "req_def456",
    "status": "in_progress",
    "previousStatus": "todo",
    "updatedAt": "2024-01-15T11:00:00.000Z"
  }
}

Error Responses

• 401 — Invalid or missing API key
• 404 — Request not found or belongs to a different space
• 422 — Invalid status transition (response includes allowed transitions)
• 429 — Rate limit exceeded

Webhooks allow you to receive real-time HTTP POST notifications when events occur in your space. Configure webhook endpoints in your space settings (Business plan required).

Event Types

• request_created — A new request was created
• request_status_changed — A request status was updated
• request_assigned — A request was assigned or reassigned
• request_closed — A request was closed

Payload Format

{
  "id": "del_abc123",
  "type": "request_status_changed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "space": {
    "id": "space_xyz",
    "slug": "engineering"
  },
  "data": {
    "requestId": "req_def456",
    "templateId": "tpl_abc123",
    "status": "in_progress",
    "previousStatus": "todo",
    "assignedToId": "user_xyz",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Signature Verification

If you configured a secret for your webhook endpoint, each delivery includes an X-Requester-Signature-256 header. Verify it using HMAC-SHA256:

import crypto from 'crypto';

function verifySignature(payload: string, secret: string, signature: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Usage in your webhook handler:
const signature = req.headers['x-requester-signature-256'];
const isValid = verifySignature(rawBody, yourSecret, signature);

Retry Behavior

Failed deliveries (non-2xx response or timeout after 10s) are retried with exponential backoff:

After 5 failed attempts, the delivery is marked as failed. Check the delivery log in space settings to troubleshoot.

The Public API enforces rate limits to ensure fair usage and system stability.

• 60 requests per minute per API key
• 429 responses include a Retry-After header indicating seconds until the next request is allowed

429 Response Example

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after the specified duration."
  }
}

Implement exponential backoff in your client when receiving 429 responses. Each API key has an independent rate limit.