API Reference

Overview

This section provides comprehensive documentation for all API endpoints. The API is organized into logical sections, each with its own documentation page.

Table of Contents

• API Overview - Base URL, authentication, request/response formats

• Forms API - Create, read, update, and delete forms

• Submissions API - Submit forms and manage responses

• Analytics API - Get analytics and insights

• Webhooks API - Manage webhook configurations

• Users & Environments API - User and environment management

• API Keys API - Manage API keys

• Billing API - Subscription and billing management

• Integrations API - Third-party integrations

• Templates API - Form templates

• Uploads API - File upload endpoints

• Tokens API - Token generation

• Feedback API - Feedback management

---

API Overview

Base URL

The API base URL depends on your deployment:

• Production: https://api.formr.xyz

• Staging: https://staging-api.formr.xyz

• Development: Your API Gateway URL from CDK deployment

Authentication

The API supports two authentication methods:

Session Authentication (Dashboard)

For dashboard operations, use Stytch session tokens:

Authorization: Bearer <stytch_session_token>

Used for:

• Form management (CRUD)

• User management

• Analytics

• Webhook management

• API key management

API Key Authentication (Programmatic)

For programmatic access, use secret API keys:

Authorization: Bearer <secret_key>

Key Formats:

• New format: sk_live_... or sk_test_...

• Legacy format: sk-live-...

Used for:

• Server-side form submissions

• Automated API access

• Integration development

Publishable Keys (Public Forms)

For public form submissions, publishable keys are optional:

x-publishable-key: pk-live-...

Used for:

• Public form submissions

• Client-side form access

Request Format

Headers

Required:

• Content-Type: application/json (for POST/PUT requests)

Optional:

• Authorization: Bearer <token> (for authenticated requests)

• x-publishable-key: pk-live-... (for public form submissions)

• X-Idempotency-Key: <uuid> (for idempotent requests)

CORS

The API supports CORS for cross-origin requests:

• Allowed Origins: * (all origins)

• Allowed Methods: GET, POST, PUT, DELETE, OPTIONS

• Allowed Headers: Content-Type, Authorization, X-Idempotency-Key, x-publishable-key, Origin

Response Format

Success Responses

200 OK: Successful GET request

201 Created: Successful POST request

204 No Content: Successful DELETE request (no body)

Error Responses

400 Bad Request: Invalid request

401 Unauthorized: Missing or invalid authentication

403 Forbidden: Insufficient permissions

404 Not Found: Resource not found

409 Conflict: Resource conflict

429 Too Many Requests: Rate limit exceeded

500 Internal Server Error: Server error

Pagination

Many list endpoints support pagination:

Query Parameters:

• limit: Number of items per page (default: 50, max: 100)

• cursor: Pagination cursor from previous response

Response Format:

{
  "items": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6IjEyMyJ9",
    "hasMore": true
  }
}

Environment Parameter

Most endpoints require or accept an environment query parameter:

GET /forms?environment=development
GET /responses?environment=production

Default Environments: development, production

Validation: Environment names must be 1-50 characters, lowercase alphanumeric with hyphens and underscores only.

Rate Limiting

The API implements rate limiting to prevent abuse:

• Public Endpoints: Rate limited by IP address

• Authenticated Endpoints: Rate limited by user

• Rate Limit Headers: Retry-After header indicates when to retry

Next Steps

• Forms API - Form management endpoints

• Submissions API - Form submission endpoints

• Dashboard Guide - Use the web dashboard