Data & automation

REST API v1

Programmatic access to forms and submissions. JSON over HTTPS, Bearer-token auth, predictable endpoints.

Base URL

https://gatherino.com/api/v1

Authentication

All requests require an API key. Create one from Settings → API keys in the dashboard. Keys start with gs_live_ and are shown once on creation — store them in a secret manager.

Pass the key as a Bearer token:

bashcurl https://gatherino.com/api/v1/forms \
  -H "Authorization: Bearer gs_live_************************"

Heads up

Never embed API keys in client-side code. Anyone with a key can read every submission in the workspace. Revoke leaked keys immediately from the dashboard.

Rate limits

By default, each workspace is allowed 120 requests per minute across all API keys. Exceeded requests return 429 Too Many Requests with a Retry-After header. Business-plan workspaces have higher limits — contact us if you need more.

Endpoints

GET/v1/formsList all forms in the workspace
GET/v1/forms/:idGet a single form with its schema
POST/v1/forms/:slug/submitSubmit data to a form programmatically
GET/v1/submissionsList submissions with filters and pagination
GET/v1/submissions/:idGet a single submission by ID
PATCH/v1/submissions/:id/statusChange submission status

Listing forms

bashGET https://gatherino.com/api/v1/forms

Example response:

json{
  "forms": [
    {
      "id": "ckx...",
      "name": "Customer feedback",
      "slug": "customer-feedback",
      "isPublished": true,
      "createdAt": "2026-03-01T12:00:00.000Z"
    }
  ],
  "total": 1
}

Listing submissions

bashGET https://gatherino.com/api/v1/submissions?formId=ckx...&status=NEW&page=1&limit=50

Query parameters

  • formId — filter to a single form
  • status — NEW, IN_PROGRESS, COMPLETED, ARCHIVED
  • search — full-text search across answer values
  • dateFrom / dateTo — ISO 8601 dates
  • page — 1-based, default 1
  • limit — max 100, default 50
  • sortBy, sortOrder — e.g. submittedAt / desc

Example response:

json{
  "submissions": [
    {
      "id": "sub_01HA...",
      "formId": "ckx...",
      "status": "NEW",
      "submittedAt": "2026-04-16T08:42:00.000Z",
      "data": {
        "field_1712345678901_a8fgh": "Jane Doe",
        "field_1712345678912_qw4er": "jane@example.com"
      }
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 128
}

Submitting data

Post a body with a data object keyed by field ID. Missing required fields return 422 Unprocessable Entity with a list of validation errors.

bashcurl -X POST https://gatherino.com/api/v1/forms/customer-feedback/submit \
  -H "Authorization: Bearer gs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "field_1712345678901_a8fgh": "Jane Doe",
      "field_1712345678912_qw4er": "jane@example.com",
      "field_1712345678923_r4t5y": 5
    }
  }'

Updating status

bashcurl -X PATCH https://gatherino.com/api/v1/submissions/sub_01HA.../status \
  -H "Authorization: Bearer gs_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "COMPLETED" }'

Errors

The API uses standard HTTP status codes:

  • 400 — malformed request
  • 401 — missing or invalid API key
  • 403 — key is valid but lacks permission for this resource
  • 404 — form or submission not found
  • 422 — validation error (body includes field-level messages)
  • 429 — rate limit exceeded
  • 500 — something went wrong on our side; safe to retry after a short delay

Versioning

The current version is v1, reflected in the URL path. Breaking changes will ship under a new version prefix; additive changes (new optional fields, new endpoints) may be rolled into v1.

Previous

Integrations

Next

Plans & billing