Schema-Backed Forms and Public API Overview

KinoForms uses form schemas to define fields and validate structured response data. People create and edit forms in the visual builder; developers and coding agents can prepare requests using the documented scoped create and edit API. Conditional logic, submission review, templates, and analytics support collection.

The public API (/papi/v1) documents form creation with name and schema, diff-based editing with operations, and structured response validation. Start with the Builder guide for request shapes and response envelopes. The public API is isolated from the internal app API and versioned independently.

Explore agentic data schema forms for the native form schema, visual editing workflow, and documented create and diff-edit examples.

Base URL:

https://dash.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": { "form": { "id": "f4d3a2e1-8b7c-4d6e-9a1f-2c3b4d5e6f70", "name": "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://dash.kinoforms.com/papi/v1/management/forms \
  -H "x-api-key: $KINOFORMS_API_KEY"

Submitter example:

curl https://dash.kinoforms.com/papi/v1/submitter/form/validation \
  -H "x-form-access-key: $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.

Integrations can follow help and _guide to diagnose validation errors and prepare a corrected request within their authorized workflow.

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.