API Reference

The Chirp Form API lets you manage forms and submissions programmatically. All requests require authentication via an API key.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Find your API key in Settings → Account settings → API.

Forms

List Forms

GET /api/forms

Returns all forms in your workspace.

[
  {
    "id": "contact-form",
    "name": "Contact Form",
    "status": "live",
    "created_at": "2026-06-17T10:00:00Z"
  }
]

Get Form

GET /api/forms/:id

Returns a form with its fields.

{
  "id": "contact-form",
  "name": "Contact Form",
  "status": "live",
  "created_at": "2026-06-17T10:00:00Z",
  "fields": [
    {
      "id": "name",
      "label": "Full Name",
      "type": "text",
      "required": true,
      "placeholder": "Enter your name"
    },
    {
      "id": "country",
      "label": "Country",
      "type": "select",
      "required": true,
      "choices": [
        {"label": "Germany", "value": "de"},
        {"label": "The Netherlands", "value": "nl"}
      ]
    }
  ]
}

Create Form

POST /api/forms
Content-Type: application/json

{
  "form": {
    "name": "Contact Form",
    "default_submission_status": "pending"
  }
}

default_submission_status is optional (defaults to approved).

{
  "id": "contact-form",
  "name": "Contact Form",
  "status": "draft",
  "created_at": "2026-06-17T10:00:00Z"
}

Submissions

List Submissions

GET /api/submissions

Optional query parameters:

Param	Description
form_id	Filter by form slug
status	Filter by status (pending, approved, spam)
limit	Maximum number of results

[
  {
    "id": "sub_abc123",
    "status": "pending",
    "created_at": "2026-06-17T10:00:00Z",
    "form": {"id": "contact-form", "name": "Contact Form"},
    "fields": [
      {"label": "Full Name", "value": "Jane Doe"},
      {"label": "Message", "value": "Hello!"}
    ]
  }
]

Get Submission

GET /api/submissions/:id

Returns a single submission with its form and field data.

Update Submission

PATCH /api/submissions/:id
Content-Type: application/json

{
  "submission": {
    "status": "approved"
  }
}

{
  "id": "sub_abc123",
  "status": "approved"
}

Errors

The API returns standard JSON error responses:

Status	Meaning
401	Unauthorized — missing or invalid API key
404	Resource not found
422	Validation error — check the errors field
400	Bad request — missing required parameters

{
  "error": "Not found"
}

{
  "errors": ["Status is not included in the list"]
}