REST API Reference

Authentication

All API requests (except GET /health) require an Authorization header:

Authorization: Bearer <your-api-key>

API keys are created and managed in the dashboard. Each key is scoped to a single project.

Error response shape

All endpoints return errors in a consistent format:

{
  "error": {
    "code": "validation_failed | not_found | unauthorized | internal_error",
    "message": "Human-readable error description",
    "details": [
      {
        "path": "fields.0.id",
        "code": "invalid_string",
        "message": "Detailed error message"
      }
    ]
  }
}

HTTP status codes: 400 (bad request), 401 (unauthorized), 404 (not found), 422 (validation failed), 500 (internal error).

Forms

`GET /health`

Health check. No authentication required.

Example response (200):

{ "ok": true }

`POST /v1/forms/validate`

Validate a form definition without creating it.

Request body: a form definition JSON object (see Form Schema Reference).

bash

curl -X POST https://api.agentsforms.com/v1/forms/validate \
  -H "Authorization: Bearer $AGENTSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @forms/example-form.json

Example response (200):

{
  "ok": true,
  "form": {
    "name": "Support Intake",
    "slug": "support-intake",
    "fields": [{ "id": "email", "type": "email", "required": true }]
  }
}

Example error (422):

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid form definition",
    "details": [
      { "path": "fields.0.id", "code": "invalid_string", "message": "Field id must start with a letter" }
    ]
  }
}

`POST /v1/forms`

Create a new form from a validated schema. The form is created in draft status.

Request body:

Field	Type	Description
`name`	`string`	Human-readable name
`slug`	`string`	URL-safe slug
`description`	`string`	Optional description
`fields`	`Field[]`	Array of field definitions
`settings`	`Settings`	Optional form-level settings

bash

curl -X POST https://api.agentsforms.com/v1/forms \
  -H "Authorization: Bearer $AGENTSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @forms/support-intake.json

Example response (201):

{
  "form": {
    "id": "form_abc123",
    "name": "Support Intake",
    "slug": "support-intake",
    "status": "draft",
    "version": 0,
    "created_at": "2026-06-23T10:00:00Z",
    "updated_at": "2026-06-23T10:00:00Z"
  }
}

`GET /v1/forms`

List all forms in the project.

Query parameters:

Parameter	Type	Description
`status`	`string`	Filter by status: `draft`, `published`, `archived`
`limit`	`number`	Max results (default 20, max 100)
`offset`	`number`	Pagination offset

bash

curl -X GET "https://api.agentsforms.com/v1/forms?status=published" \
  -H "Authorization: Bearer $AGENTSFORMS_API_KEY"

Example response (200):

{
  "forms": [
    {
      "id": "form_abc123",
      "name": "Support Intake",
      "slug": "support-intake",
      "status": "published",
      "version": 1,
      "submission_count": 42,
      "updated_at": "2026-06-23T10:00:00Z"
    }
  ]
}

`GET /v1/forms/:id`

Get a single form by ID.

Example response (200):

{
  "form": {
    "id": "form_abc123",
    "name": "Support Intake",
    "slug": "support-intake",
    "status": "published",
    "version": 1,
    "definition": {
      "name": "Support Intake",
      "slug": "support-intake",
      "fields": [{ "id": "email", "type": "email", "required": true }]
    },
    "created_at": "2026-06-23T10:00:00Z",
    "updated_at": "2026-06-23T10:00:00Z"
  }
}

`POST /v1/forms/:id/publish`

Publish a draft form. Creates a new version if the definition changed; reuses the last version if the checksum matches.

Example response (200):

{
  "form": {
    "id": "form_abc123",
    "slug": "support-intake",
    "status": "published",
    "version": 1,
    "hosted_url": "https://agentsforms.com/f/support-intake"
  }
}

Sessions

`POST /v1/forms/:id/sessions`

Create a new form-filling session.

Request body:

Field	Type	Description
`expires_in`	`number`	Session lifetime in seconds (default 3600)
`prefill`	`object`	Key-value prefill map by field `id`
`metadata`	`object`	Arbitrary key-value metadata attached to the session

Planned response (201):

{
  "session": {
    "id": "sess_xyz789",
    "form_id": "form_abc123",
    "status": "open",
    "url": "https://agentsforms.com/f/sess_xyz789",
    "expires_at": "2026-06-23T11:00:00Z"
  }
}

`GET /v1/sessions/:id`

Get a session by ID. Returns the session status and any partial answers if allowPartial is enabled.

`PATCH /v1/sessions/:id`

Update a session (e.g., extend expiry, add prefill data).

`POST /v1/sessions/:id/submit`

Force-submit a session. Normally the human user submits via the form UI; this endpoint allows an agent to auto-submit on the user’s behalf.

Submissions

`POST /v1/forms/:id/submissions`

Retrieve submissions for a form. (Exact method TBD — may be GET with filtering.)

`GET /v1/forms/:id/submissions`

List submissions for a form with pagination and filtering.

`GET /v1/submissions/:id`

Get a single submission by ID with full answer data.

Webhooks

`POST /v1/webhooks`

Planned request body:

Field	Type	Description
`url`	`string`	HTTPS URL to receive webhook events
`events`	`string[]`	Event types: `submission.created`, `session.expired`
`secret`	`string`	Optional HMAC signing secret

`GET /v1/webhooks`

List registered webhooks.

`GET /v1/webhooks/:id`

Get a webhook by ID.

`DELETE /v1/webhooks/:id`

Delete a webhook.

`GET /v1/webhooks/:id/deliveries`

List delivery attempts for a webhook, with status and timestamps.

`POST /v1/webhook-deliveries/:id/replay`

Replay a failed webhook delivery.

Hosted form page

`GET /f/:sessionId`

Renders the hosted form page for a human user to fill out. This endpoint returns HTML, not JSON.