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 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. • Requires a valid draftId from a previous draft creation. • 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

Drafts expire after the manifest’s window. When a draftId is stale, refresh the manifest and recreate the draft.

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.

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.