Agents

Public Fill

NativeForm exposes a public agent-fill protocol that any AI agent can discover. The flow is always the same: fetch the manifest to understand field requirements, generate a draft that lines up with those rules, then submit the draft or hand it off for human confirmation when APIs are unavailable.

This page documents the auth-free public contract. For private management scenarios that require keys, see Get an API Key and the Agents Auth guide.

Agents visiting nativeform.app directly can reference the 3-step walk-through in If you're an AI.

Key headers

Set x-nativeform-agent for every draft/submission request. Include x-nativeform-agent-version and x-nativeform-agent-channel when available for attribution.

Honor Retry-After from 429 responses and respect the manifest’s rateLimits hints before calling write endpoints.

Manifest + endpoints

Every public form exposes a manifest that describes fields, validation, instructions, and rate limits. Read it before you build a draft or submit a response so you know what the server expects.

Method	Endpoint	Description
GET	`/api/public/forms/{slug}/ai-manifest`	Returns the form schema, field definitions, rate limits, and agent instructions. • Use this endpoint to discover form structure before submitting. • Returns field keys, types, required flags, and validation rules.
POST	`/api/public/forms/{slug}/drafts`	Creates a draft response with partial or complete answers. • Returns a secret draftToken for draft submission, plus a separate confirmation token and URLs for human review. • Drafts expire after the time specified in the manifest.
POST	`/api/public/forms/{slug}/submissions`	Finalizes a draft into a submitted response. • When reusing a draft, requires its draftId and secret draftToken. One-shot submissions can send complete answers without a draft. • Validates all required fields are present before accepting.
GET	`/api/public/confirm/{token}`	Renders the human confirmation page for a draft. • Used in the ChatGPT fallback flow. • Displays prefilled answers for the user to review and confirm.
POST	`/api/public/confirm/{token}`	Confirms and submits the draft via the human review flow. • Triggered when the user clicks 'Confirm' on the review page.

Draft flow

Step 1: read the manifest, map user answers to field keys, gather respondent info, and call the drafts endpoint with the required headers.

POST/api/public/forms/{slug}/drafts

Request Body

answersarrayRequired

Array of field answers. Each entry maps a fieldKey to its value.

fieldKeystring

The key of the form field to fill.

valuestring | number | boolean

The answer value matching the field type.

respondentobject

Optional identification of the person submitting.

externalIdstring

Your application's user ID.

displayNamestring

Display name shown in responses.

contactobject

Contact info, e.g. { email: "ada@lovelace.ai" }.

metadataRecord<string, unknown>

Optional metadata stored with the response for tracking purposes.

Example request

Example response

Draft access expires after 72 hours of inactivity. If the token is missing, expired, or from a legacy tokenless draft, create a new draft. Confirmation links keep their separate expiry.

Submit flow

Step 2: once your draft has every required field, POST it to submissions. The server validates the active manifest and rejects the call if anything changed while you were drafting.

POST/api/public/forms/{slug}/submissions

Request Body

draftIdstringRequired

The draft ID returned from the drafts endpoint. Omit for a one-shot submission.

draftTokenstringRequired

Required with draftId. Keep the token returned by draft creation private; the response ID alone grants no access.

answersarrayRequired

Complete set of field answers. Must include all required fields.

fieldKeystring

The key of the form field.

valuestring | number | boolean

The final answer value.

Example request

Human confirmation

When APIs are blocked, fall back to the confirmation URL that arrives with every draft. The user opens the prefilled /public/confirm/{token} page, validates the answers, and clicks confirm to finish the submission.

1. Create draft

Agent creates a draft through POST /api/public/forms/{slug}/drafts.

2. Share confirmation link

Agent shares confirmation.webUrl with the user as a clickable link.

3. User confirms

User opens /public/confirm/{token} and reviews prefilled answers before confirming submission.

Discovery

Public form pages and embed pages include machine-readable markers and JSON instructions for agents.

HTML meta tags

Public form pages expose nativeform:ai-manifest and nativeform-agent-instructions tags so agents know the form is agent-fillable.

AI manifest endpoint

Fetch /api/public/forms/{slug}/ai-manifest to learn required fields, validation, instructions, and rate limits before you fill anything.

Agent headers

Every POST draft/submission requires x-nativeform-agent; include x-nativeform-agent-version and x-nativeform-agent-channel when you can for attribution.

Error handling

Respect 422 fieldErrors, 429 Retry-After, and documented error codes while keeping user context so retries stay accurate.

Errors

Public endpoints return typed error envelopes with stable codes.

Status	Code	Description
422	`VALIDATION_ERROR`	One or more fields failed validation. Check fieldErrors for per-field details and prompt the user for corrections.
403	`POLICY_DISABLED`	Public AI fill is disabled for this form. The form owner must enable it in form settings.
429	`RATE_LIMITED`	Too many requests. Honor the Retry-After header and back off before retrying.
400	`INVALID_CONFIRM_TOKEN`	The confirmation token is expired or invalid. Create a new draft to get a fresh token.

Use fieldErrors for precise follow-up prompts and honor Retry-After on 429 responses.