Agents

Public Fill

NativeForm exposes a dedicated public agent-fill protocol. Agents discover the schema from the manifest, create drafts, then submit directly or through confirmation links.

For private management APIs that require authentication, use API keys and follow the Agents Auth guide.

AI agents visiting nativeform.app can find a short guide at If you're an AI.

Endpoints

Canonical public routes for AI-assisted form filling. No API key required.

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 Request

Create a draft response with partial or complete answers.

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

Submit Request

Finalize a draft into a submitted response.

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

ChatGPT Fallback

If an assistant cannot call APIs directly, return confirmation.webUrl. The user opens the link and confirms submission in a human UI.

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 meta tags for agent discovery.

AI manifest endpoint

Read schema, field definitions, and rate limits from /api/public/forms/{slug}/ai-manifest.

Required headers

Send x-nativeform-agent (required) plus optional version and channel headers when posting drafts and submissions.

Error handling

Handle 422 fieldErrors and 429 Retry-After without dropping collected context.

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.