# API Reference

Canonical: https://useformwork.com/docs/api/reference

Find the OpenAPI specification and the main API areas available for integrations.

The FormWork API is available for teams that need custom integrations, reporting, migrations, or developer-built workflows around FormWork data.

Most users do not need to use the API directly. Start with the builder, workflows, extensions, API Connectors, imports, and exports before building a direct integration.

## Interactive API Docs

Use the interactive OpenAPI documentation for full endpoint details, request fields, and response examples.

<div class="not-prose api-docs-panel">
  <div class="api-docs-summary">
    <span class="api-docs-mark" aria-hidden="true">API</span>
    <div>
      <h3>Explore every endpoint</h3>
      <p>Browse request fields, schemas, authentication details, and response examples in the generated OpenAPI reference.</p>
    </div>
  </div>
  <a href="https://app.useformwork.com/api/v1/openapi" target="_blank" rel="noopener" class="api-docs-link">
    Open API docs
    <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
      <path stroke-linecap="round" stroke-linejoin="round" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
    </svg>
  </a>
</div>

## OpenAPI Specification

| Format | URL |
|--------|-----|
| JSON | [openapi.json](https://app.useformwork.com/api/v1/openapi.json) |
| YAML | [openapi.yaml](https://app.useformwork.com/api/v1/openapi.yaml) |

## Authentication

API keys are managed from account settings.

Send the key in the `Authorization` header and identify its account with `X-Account-ID` on account-scoped routes:

```bash
curl "https://app.useformwork.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID"
```

See [API Keys](/docs/platform/api-keys) for creating and managing keys.

The account header must match the key's account. The key uses the identity and account role of its creator, so it cannot bypass Admin-only endpoint checks.

Respondent entry-session endpoints use `X-Formwork-Entry-Key` after an entry is created. Do not expose account API keys in browser code or use an entry key as account authentication.

## Base URL and errors

The production base is:

```text
https://app.useformwork.com/api/v1
```

Successful list responses commonly contain `data` and pagination metadata. Errors return an HTTP status plus a stable error code and message. Handle at least authentication/forbidden responses, validation errors, `402 billing_inactive`, not-found responses, conflict-style state errors, and transient server/network failures according to the endpoint contract.

## Main API Areas

| Area | What it is for |
|------|----------------|
| Accounts and users | Manage account details, users, roles, and account switching. |
| Billing | Read billing status and create checkout or billing portal sessions. |
| Projects | Create and manage projects. |
| Forms and form versions | Create forms, edit drafts, validate versions, publish, and manage fields. |
| Entry sessions | Public form rendering, answer updates, repeatable groups, submission, buttons, draft resume, and upload flow. |
| Entries and revisions | Admin entry management, answers, metafields, files, edit sessions, revisions, and workflow runs. |
| Data tables | Create tables and manage rows for structured operational data. |
| Workflows | Manage workflow definitions, triggers, steps, connections, runs, and run details. |
| References | Search and resolve references used by workflows, templates, and mappings. |
| Views, imports, and exports | Saved entry views, CSV imports, exports, and background job tracking. |
| Files and jobs | Prepare uploads, complete uploads, download files, and track background jobs. |
| Extensions | Manage installed extensions, API Connectors, environments, secrets, actions, and webhooks. |
| Templates | Manage reusable content and layout templates. |

## Public Form Endpoints

Embedded forms use public entry-session endpoints behind the scenes. These endpoints support:

- Loading a public form schema before an entry exists
- Creating a draft entry
- Updating answers
- Adding and removing repeatable group instances
- Submitting an entry
- Handling button clicks
- Supporting draft resume flows
- Uploading files
- Calling entry-scoped extension actions

For normal embeds and host-page coordination, use the [Web Component & JavaScript API](/docs/embedding/web-component) instead of calling these endpoints directly. Use the entry-session endpoints when you are deliberately building and maintaining your own complete form interface.

## When to Use the API

Use the API when you need to:

- Move data between FormWork and another system
- Build custom reporting
- Create or update entries from another application
- Automate project or form setup
- Connect a process that is too specific for a no-code workflow alone

Use an [API Connector](/docs/extensions/api-connectors) when an external service should be called from a workflow step. Use the REST API when the external system needs to manage FormWork data directly.