> ## Documentation Index
> Fetch the complete documentation index at: https://formcarry.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Formcarry API Overview

> Base URL, versioning, authentication, pagination, and error format for the Formcarry v1 REST API at api.formcarry.com.

The Formcarry API lets you manage forms, submissions, email notifications, and account resources programmatically. All requests are JSON over HTTPS and authenticated with a Bearer token.

## Base URL

```text theme={null}
https://api.formcarry.com
```

Every endpoint is versioned under the `/v1` prefix, for example `GET https://api.formcarry.com/v1/forms`.

## Authentication

Formcarry uses Bearer token authentication. Pass your API key in the `Authorization` header on every request:

```bash theme={null}
curl https://api.formcarry.com/v1/me \
  -H "Authorization: Bearer fc_live_your_api_key"
```

See [Authentication](/docs/api/authentication) for details on generating keys, scopes, and verifying credentials.

## Common resources

<CardGroup cols={2}>
  <Card title="Forms" icon="rectangle-list" href="/docs/api-reference/forms/list-forms">
    Create, list, update, and delete forms in your workspace.
  </Card>

  <Card title="Submissions" icon="inbox" href="/docs/api-reference/submissions/list-submissions">
    Read, filter, and manage submissions on a form.
  </Card>

  <Card title="Email notifications" icon="envelope" href="/docs/api-reference/forms/add-a-recipient">
    Manage self-email recipients and connected email servers.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/api-reference/forms/add-a-webhook">
    Subscribe HTTPS endpoints to receive every submission as a signed JSON POST.
  </Card>

  <Card title="Account" icon="user" href="/docs/api-reference/me/retrieve-the-current-key-or-connection">
    Inspect the authenticated key with `GET /v1/me`.
  </Card>
</CardGroup>

## Pagination

List endpoints (such as `GET /v1/forms` and `GET /v1/forms/{form_id}/submissions`) use cursor pagination. Pass `limit` and `cursor` as query parameters; responses include a `next_cursor` field when more results are available.

```bash theme={null}
curl "https://api.formcarry.com/v1/forms?limit=50" \
  -H "Authorization: Bearer fc_live_your_api_key"
```

To fetch the next page, send the returned `next_cursor` back as the `cursor` parameter.

## Errors

The API returns a unified error envelope with a machine-readable `code` and a human-readable `message`. Every error response carries `request_id`, and every response carries an `X-Request-Id` header, which Formcarry support can use to trace the call.

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "missing_bearer",
    "message": "Authorization header is required.",
    "request_id": "req_01H..."
  }
}
```

Common error codes:

| Code                     | Meaning                                                                           |
| ------------------------ | --------------------------------------------------------------------------------- |
| `missing_bearer`         | No `Authorization` header on the request.                                         |
| `invalid_key`            | The API key is malformed or has been revoked.                                     |
| `wrong_audience`         | The key is not valid for this API.                                                |
| `insufficient_scope`     | The key does not have the required scope.                                         |
| `form_access_restricted` | The key cannot access the requested form.                                         |
| `team_inactive`          | The workspace is suspended.                                                       |
| `owner_unverified`       | The account owner has not verified their email.                                   |
| `plan_restricted`        | The action requires a higher plan.                                                |
| `rate_limited`           | Too many requests. Retry after the delay in the `Retry-After` header.             |
| `invalid_parameter`      | A request parameter failed validation.                                            |
| `form_not_found`         | The `form_id` does not exist or is not visible to this key.                       |
| `invalid_cursor`         | The pagination cursor is malformed or expired.                                    |
| `payload_too_large`      | The request body exceeded the size limit (1 MB for JSON, 5 MB for image uploads). |
| `recipient_not_found`    | The email address is not on the notification list.                                |
| `webhook_limit_reached`  | The form already has its 10 webhooks. Delete one to add another.                  |
| `webhook_url_taken`      | Another webhook on this form already posts to that URL.                           |
| `scan_concurrency`       | At most 2 filtered submission requests may run at once per key.                   |

## Rate limits

Formcarry enforces per-key rate limits. When you exceed a limit, requests return HTTP `429` with `code: "rate_limited"`. Respect the `Retry-After` response header before retrying.

## Reference

Every endpoint, request schema, and response schema is documented in the [Endpoints](/docs/api-reference/forms/list-forms) section, generated directly from the live OpenAPI specification at `https://api.formcarry.com/docs-json`.


## Related topics

- [Legacy Formcarry API Overview](/docs/api/legacy/overview.md)
- [API Authentication with Bearer Tokens](/docs/api/authentication.md)
- [Legacy API Authentication](/docs/api/legacy/authentication.md)
- [Legacy Forms API — Create and Delete Forms](/docs/api/legacy/forms.md)
- [Legacy Submissions API — List and Filter Submissions](/docs/api/legacy/submissions.md)