API Overview & Authentication

The ResponseDock REST API is available at https://api.responsedock.com/v1. All requests and responses use JSON. All endpoints require authentication unless noted.

Authentication

There are two authentication methods:

JWT (Admin Dashboard)

The admin dashboard uses session JWTs obtained via the Google OAuth flow. Pass the token as a Bearer header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Public API Key (SDK)

For browser SDK event tracking, use a workspace public key. ResponseDock sends it in theX-Project-Key header.

X-Project-Key: pk_live_xxxxxxxxxxxxxxxxxxxx

Create API keys in Workspace → Settings → API Keys.

Base URL

https://api.responsedock.com/v1

For self-hosted instances replace with your own domain.

Response Format

Successful responses return the resource directly or in a data wrapper:

// Single resource
{
  "id": "survey_xxxx",
  "title": "Post-event feedback",
  ...
}

// Collection: items under a resource-named key, plus pagination fields
{
  "surveys": [...],
  "total": 42,
  "page": 1,
  "pageSize": 20
}

Error Format

{
  "error": "NOT_FOUND",
  "message": "Survey not found",
  "statusCode": 404
}

HTTP Status Codes

Plan and Verification Errors

When the workspace's plan does not include a feature, a plan limit is reached, or the action needs a verified email address, the API answers 403 with a machine-readable code. Switch on code; the error sentence is for people.

// The plan does not include the feature
{
  "error": "Webhooks are included in the Pro plan and above. ...",
  "code": "PLAN_FEATURE_REQUIRED",
  "feature": "webhooks",          // webhooks | apiKeys | sdk | whiteLabel | customDomain | registrationForms | emailDistribution | zapier | chatNotifications
  "requiredTier": "PRO"           // PRO | BUSINESS | ENTERPRISE
}

// A plan limit is reached
{
  "error": "Your plan includes up to 5 surveys. ...",
  "code": "PLAN_LIMIT_REACHED",
  "limit": "surveys",             // surveys | responses | workspaces | seats | aiGenerations | emailInvites
  "current": 5,
  "max": 5,
  "requiredTier": "PRO",
  "periodEnd": "2026-11-01T00:00:00.000Z", // monthly limits only (responses, aiGenerations, emailInvites)
  "limitedByTrial": true          // only when a trial, not the paid plan, sets the limit
}

// The action needs a verified email address
{
  "error": "Verify your email before creating API keys.",
  "code": "EMAIL_VERIFICATION_REQUIRED",
  "feature": "apiKeys"
}

requiredTier is the lowest plan that removes the block; ENTERPRISE is the custom Platform plan. Unverified accounts can try the AI designer a few times before verifying.

Rate Limiting

Default: 100 requests per minute per API key. Limits are shown in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1700000060

Pagination

Paginated collections take page (1-based) and pageSize query parameters and echo them back with the total count:

GET /workspaces/:wid/surveys?page=2&pageSize=20
GET /surveys/:sid/responses?page=1&pageSize=200

The default page size is 20 for surveys and 50 for responses. Response lists accept at most 200 per page.