API Keys and the Public API

Revuloop provides a comprehensive Public API (v1) with 99+ endpoints for programmatic access to surveys, responses, analytics, webhooks, and more.

Getting Started

Creating an API Key

1. Go to your Organization Settings
2. Navigate to API Keys
3. Click Create New Key
4. Select environment: LIVE or TEST
5. Copy the key immediately (shown only once)

API Key Format

• Live keys: `rlk_live_` followed by a 64-character hex string
• Test keys: `rlk_test_` followed by a 64-character hex string

Test keys work against the same API but are tracked separately for development.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer rlk_live_your_key_here

Rate Limits

Exceeding rate limits returns a `429 Too Many Requests` response.

Key API Endpoints

Surveys

• `GET /api/v1/surveys` - List your surveys
• `POST /api/v1/surveys` - Create a survey
• `POST /api/v1/surveys/generate` - AI-generate a survey from a prompt
• `POST /api/v1/surveys/{id}/launch` - Launch a survey
• `POST /api/v1/surveys/{id}/pause` - Pause a survey

Responses

• `GET /api/v1/surveys/{id}/responses` - List responses
• `POST /api/v1/surveys/{id}/responses` - Submit a response
• `POST /api/v1/surveys/{id}/responses/export` - Export responses

Analytics

• `GET /api/v1/surveys/{id}/analytics/static` - Quantitative stats
• `POST /api/v1/surveys/{id}/analytics/ai/generate` - Trigger AI analysis
• `GET /api/v1/surveys/{id}/analytics/smart` - Smart survey analytics

Webhooks

• `POST /api/v1/webhooks` - Create a webhook subscription
• `GET /api/v1/webhooks/{id}/deliveries` - View delivery history

Scopes

API keys use a hierarchical scope system:

• `surveys:read`, `surveys:write`, `surveys:launch`
• `responses:read`, `responses:write`, `responses:delete`
• `analytics:read`, `analytics:generate`
• `webhooks:read`, `webhooks:write`
• `*` (full access)

Wildcard scopes are supported: `surveys:*` grants all survey permissions.

API Response Format

All responses follow a consistent format:

{
  "data": { ... },
  "meta": {
    "requestId": "...",
    "timestamp": "...",
    "apiVersion": "v1"
  }
}

Paginated responses include a `pagination` object with `page`, `pageSize`, `totalItems`, `totalPages`, and `hasMore`.

Managing API Keys

• `GET /api/v1/api-keys` - List all keys
• `POST /api/v1/api-keys` - Create a new key
• `DELETE /api/v1/api-keys/{id}` - Revoke a key