Helios Gather API

Quickstart

Create an API key from Developer / Integration in your signed-in workspace. The full key is displayed once. Keep it in a server-side secret store.

curl "https://forms.lucionglobal.com/api/v1/forms?limit=50" \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "X-Gather-API-Version: 1"

Do not place API keys in browser code, public repositories, URLs, or logs.

Authentication and limits

• Send the key as an HTTP Bearer token and include X-Gather-API-Version: 1.
• Keys belong to one workspace and can be revoked by an Owner or Admin. Key scopes are forms:read and responses:read.
• Rate limit: 120 requests per minute per key. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
• All responses are private and marked Cache-Control: no-store. Browser CORS access is not supported.

API reference

GET /api/v1/forms

List forms in the key’s workspace. Query parameters: limit (1–100, default 50) and opaque cursor. Returns data plus meta.nextCursor.

GET /api/v1/forms/{formId}/responses

List submitted responses for a form in the same workspace. Requires responses:read; returns response IDs, submitted and started timestamps, and answers. Draft responses and forms from other workspaces are not returned.

Errors

Errors use { "error": { "code": "...", "message": "..." } }. Common status codes: 400 invalid version/query, 401 missing/revoked/expired key, 403 missing scope, 404 form not found, 429 rate limit. Every response includes X-Request-ID.

Webhooks

Subscribe to response.submitted in Developer / Integration. The signing secret is displayed once; Gather stores it encrypted with WEBHOOK_SECRET_ENCRYPTION_KEY (a base64-encoded 32-byte key).

Each POST contains id, type, createdAt, and data with response ID, form ID, and submission time. Answers are omitted.

Headers: X-Gather-Event, X-Gather-Delivery, X-Gather-Timestamp, and X-Gather-Signature. Verify HMAC-SHA256 over timestamp + "." + rawRequestBody; reject timestamps older than five minutes. Gather does not follow redirects. Delivery attempts and safe status codes are visible in the integration area.

Webhook delivery requires the encryption key to be configured in the Worker environment. Endpoint servers should verify the signature before processing and deduplicate by delivery ID.

Generate a 32-byte encryption key with openssl rand -base64 32. For local development, place it in the repository-root .dev.vars; for Cloudflare, use npx wrangler secret put WEBHOOK_SECRET_ENCRYPTION_KEY --config apps/web/wrangler.jsonc. Do not commit the value.

Gather currently makes up to three bounded attempts during response handling. Failed deliveries remain visible in the integration area; there is no automatic later replay queue yet.