# API

The Formspark API lets you create forms, change their settings, and read their submissions from your own code.

The API is available on upgraded workspaces. Listing your workspaces and reading your own token stay open on any plan, so a client can always discover which workspace qualifies. See [limits and plans](https://documentation.formspark.io/troubleshooting/limits-and-plans.md).

## Base URL

```
https://api.formspark.io/public/v1
```

## Authentication

Create an API token in your [dashboard](https://dashboard.formspark.io/account/api-tokens) and send it as a bearer token:

```sh
curl https://api.formspark.io/public/v1/me \
  -H "Authorization: Bearer fsk_live_..."
```

A token reaches every workspace you are a member of, limited to its [scopes](https://documentation.formspark.io/api/api-tokens.md).

`GET /me` describes the token you are using:

```json
{
  "name": "CI",
  "scopes": ["forms:read", "submissions:read"],
  "expiresAt": "2027-01-14T00:00:00.000Z",
  "lastUsedAt": "2026-07-29T09:12:44.000Z",
  "createdAt": "2026-07-01T08:30:00.000Z"
}
```

## OpenAPI

The API is described by an OpenAPI 3.1 document, which you can use to generate a client:

```
https://api.formspark.io/public/v1/openapi.json
```

## Using the API from an AI agent

An agent such as Claude or Cursor can use the API the same way your code does. Give it two things:

1. An API token with only the [scopes](https://documentation.formspark.io/api/api-tokens.md) it needs, for example `forms:read` and `submissions:read` to answer questions about your submissions.
2. The OpenAPI document above, which describes every endpoint it can call.

For example, to list a workspace's forms and read one form's latest submissions:

```sh
curl "https://api.formspark.io/public/v1/forms?workspaceId=<workspace-id>" \
  -H "Authorization: Bearer fsk_live_..."

curl "https://api.formspark.io/public/v1/forms/<form-id>/submissions" \
  -H "Authorization: Bearer fsk_live_..."
```

Treat the token like a password. Revoke it from the dashboard once the agent no longer needs it.

## Versioning

The version is in the path. Within `v1`, new optional fields and new endpoints can appear at any time, so ignore fields you do not recognize. Changes that would break a working integration ship as a new version.

## Retries

`GET` requests are safe to retry.

Retry a write only after checking whether it landed: a repeated `POST` creates a second form or workspace.

## Rate limits

Requests are limited per IP address. Sustained bursts from one address are blocked for a period. If you are planning something high-volume, [get in touch](https://dashboard.formspark.io/support/contact) first.