Public API Overview

The KinoForms public API (/papi/v1) is a stable, self-describing API for building integrations and AI agents on top of KinoForms. It is isolated from the internal app API and versioned independently.

Base URL:

https://api.kinoforms.com/papi/v1

The Response Envelope

Every /papi/v1 response is enveloped. You never get a bare object or array at the top level.

A successful (2xx) response wraps the result in data:

{
  "data": { "id": "form_123", "title": "Contact us" },
  "apiVersion": "v1",
  "_docs": "https://docs.kinoforms.com/developer/api-reference",
  "_guide": "https://docs.kinoforms.com/developer/overview"
}

An error response replaces data with error and a stable machine code:

{
  "error": "Validation failed",
  "code": "validation_failed",
  "errors": [
    {
      "field": "email",
      "code": "format",
      "message": "Value is not a valid email address.",
      "help": "https://docs.kinoforms.com/developer/api/validation#format"
    }
  ],
  "apiVersion": "v1",
  "_docs": "https://docs.kinoforms.com/developer/api-reference",
  "_guide": "https://docs.kinoforms.com/developer/api/validation#validation_failed"
}

Envelope fields:

• data: present on success only. The actual payload.
• error: present on error only. A human-readable message.
• code: present on error only. A stable machine-readable code. Branch on this, not on the message text.
• errors: an optional array of per-field problems. See Parsing validation responses.
• apiVersion: always "v1".
• _docs: a link to the API reference (always {DOCS_BASE}/developer/api-reference).
• _guide: a link to the most relevant guide. On success this is always the overview; on error it is the validation reference with the error code as the anchor (e.g. .../developer/api/validation#validation_failed).

Because code is stable, always branch on it instead of parsing error strings.

Three Ways In

There are three entry paths into a KinoForms form, depending on who is submitting.

Caller	Path	Auth
A human in a browser	The existing public form runtime (/public)	Magic link / password / none
An AI agent	/papi/v1 submitter endpoints	Agent session token
An anonymous web client	/papi/v1 submitter endpoints	Anonymous session (CAPTCHA-gated)

• Human path: People filling out forms use the published form link (https://www.kinoforms.com/f/<accessKey>). This is the existing public runtime and is documented in the Public Forms user guide. You do not need the public API for this.
• AI agent path: Agents register an identity, are granted scopes on a form by an operator, exchange their secret for a session token, then validate and submit. Start with the Agent quickstart.
• Anonymous web path: For untrusted web clients, an anonymous session is available when a form enables CAPTCHA (Turnstile). Agents are exempt from CAPTCHA and never use this path. See Anonymous sessions.

Auth Headers

/papi/v1 uses different credentials for the builder and submitter sides.

Side	Header	Credential
Builder (forms CRUD)	x-api-key	An API key (scopes forms:read, forms:write)
Submitter (validate/submit)	x-respondent-token	A session token from POST /papi/v1/auth/token

Builder example:

curl https://api.kinoforms.com/papi/v1/forms \
  -H "x-api-key: $KINOFORMS_API_KEY"

Submitter example:

curl https://api.kinoforms.com/papi/v1/validate/$ACCESS_KEY \
  -H "x-respondent-token: $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "data": { "email": "[email protected]" } }'

API keys are created in the app under Settings > API Keys (see API Keys). Never put an API key or an agent secret in client-side code.

Built for Agents

/papi/v1 is designed so that an autonomous agent can find its own way:

• Every response carries _docs and _guide pointers to the relevant documentation.
• Every per-field validation error carries a help URL that deep-links to the exact fix (for example .../developer/api/validation#format).
• The API is self-describing: fetch the machine spec from GET /papi/v1/openapi.json or open the interactive reference at GET /papi/v1/docs. See API reference.

An agent that hits an error can follow help/_guide, correct its request, and retry without human help.

Where to Go Next

• Builder guide — create and edit forms with an API key.
• Submitter guide — sessions, validate vs submit, partial save.
• Agent quickstart — the full register-to-submit loop.
• Parsing validation responses — self-correction.
• Validation reference — every error code.
• API reference — the live, interactive spec.