Forms

Form and submission endpoints

Forms

Create forms, manage fields, and retrieve submissions.

Endpoints

GETList Forms POSTCreate Form POSTSubmit Form GETList Submissions

GET/v1/forms/{tenant_id}

List Forms

Retrieve all forms in your tenant.

Requires API Key

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.

Query Parameters

Name	Type	Default	Description
`page`	integer	1	Page number.
`per_page`	integer	25	Results per page.

curl -X GET "https://api.knitt.co/v1/forms/ten_abc123?page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns a paginated list of forms.

{
  "data": [
    {
      "id": "frm_abc123",
      "name": "Contact Form",
      "slug": "contact-form",
      "fields": [
        {
          "name": "name",
          "type": "text",
          "required": true
        },
        {
          "name": "email",
          "type": "email",
          "required": true
        },
        {
          "name": "message",
          "type": "textarea",
          "required": true
        }
      ],
      "submission_count": 84,
      "created_at": "2026-01-10T08:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 5
  }
}

POST/v1/forms/{tenant_id}

Create Form

Create a new form with field definitions.

Requires API Key

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.

Request Body

Name	Type	Required	Description
`name`	string	Yes	Display name for the form.
`slug`	string	No	URL-friendly slug. Auto-generated from name if omitted.
`fields`	array	Yes	Array of field definitions.
`notify_email`	string	No	Email address to notify on new submissions.

curl -X POST "https://api.knitt.co/v1/forms/ten_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Contact Form",
  "fields": [
    {
      "name": "name",
      "type": "text",
      "required": true
    },
    {
      "name": "email",
      "type": "email",
      "required": true
    },
    {
      "name": "message",
      "type": "textarea",
      "required": true
    }
  ],
  "notify_email": "team@example.com"
}'

Response

Returns the created form.

{
  "data": {
    "id": "frm_abc123",
    "name": "Contact Form",
    "slug": "contact-form",
    "fields": [
      {
        "name": "name",
        "type": "text",
        "required": true
      },
      {
        "name": "email",
        "type": "email",
        "required": true
      },
      {
        "name": "message",
        "type": "textarea",
        "required": true
      }
    ],
    "notify_email": "team@example.com",
    "created_at": "2026-01-10T08:00:00Z"
  }
}

POST/v1/forms/{tenant_id}/{form_id}/submissions

Submit Form

Submit data to a form. This is typically called from your frontend. Does not require API key authentication — uses the form’s public slug.

Public

Form submissions do not require an API key. Rate limited to 10 submissions per minute per IP.

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.
`form_id`	string	The ID or slug of the form.

Request Body

Name	Type	Required	Description
`fields`	object	Yes	An object of field values matching the form schema.

curl -X POST "https://api.knitt.co/v1/forms/ten_abc123/contact-form/submissions" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "message": "Hi, I have a question about your API."
  }
}'

Response

Returns the created submission.

{
  "data": {
    "id": "sub_xyz789",
    "form_id": "frm_abc123",
    "fields": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "message": "Hi, I have a question about your API."
    },
    "created_at": "2026-02-01T16:45:00Z"
  }
}

GET/v1/forms/{tenant_id}/{form_id}/submissions

List Submissions

Retrieve all submissions for a form.

Requires API Key

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.
`form_id`	string	The ID of the form.

Query Parameters

Name	Type	Default	Description
`page`	integer	1	Page number.
`per_page`	integer	25	Results per page.
`sort`	string	-created_at	Sort field. Prefix with - for descending.

curl -X GET "https://api.knitt.co/v1/forms/ten_abc123/frm_abc123/submissions?page=1&per_page=25&sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns a paginated list of submissions.

{
  "data": [
    {
      "id": "sub_xyz789",
      "form_id": "frm_abc123",
      "fields": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "message": "Hi, I have a question about your API."
      },
      "created_at": "2026-02-01T16:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 84
  }
}

Last updated: February 7, 2026