# API Reference

> Use the StaticForm REST API to submit forms, list submissions, manage forms, and automate everything from your own scripts.

import { companyConfig } from '../../config';

StaticForm exposes a REST API that powers both the dashboard and external integrations. You can use it to automate form management, pull submissions into your own systems, or build custom tooling on top of the product.

## Interactive API Docs

The full API reference is available as an interactive explorer at:

**[api.staticform.app/docs](https://api.staticform.app/docs)**

It includes every endpoint with request/response schemas, authentication details, and the ability to try API calls directly from your browser. The reference is powered by [Scalar](https://scalar.com) and generated from the OpenAPI spec.

## Base URL

API endpoints are versioned and follow this pattern:

```
https://api.staticform.app/api/v{version}/...
```

The current version for most endpoints is **v1**. Check the [interactive API docs](https://api.staticform.app/docs) for the exact version of each endpoint.

## Authentication

There are two ways to authenticate with the API:

### 1. API Key (recommended for scripts & integrations)

Create an API key from **Settings → API Keys** in the dashboard (see [Account Settings](/docs/account-settings#api-keys)). The plain key is shown only once, so copy it immediately.

Pass the key in the `X-API-Key` header on every request:

```http
X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

API keys inherit the permissions of the user who created them and can be revoked at any time from the dashboard. Set an expiration date when creating the key if you want it to roll over automatically.

### 2. JWT Bearer token (used by the dashboard)

The dashboard uses short-lived JWT access tokens from the identity provider, passed as a `Bearer` token:

```http
Authorization: Bearer eyJhbGciOi...
```

This flow is intended for browser sessions. For programmatic use, prefer API keys.

### Public endpoint: form submission

The **form submission endpoint** (`POST /api/v1/forms/{formId}`) is public and does **not** require authentication: that's what lets your static HTML forms post to it directly. Every other endpoint requires an API key or JWT.

## Quick Examples

### Submit a form (public, no auth)

```bash
curl -X POST https://api.staticform.app/api/v1/forms/YOUR_FORM_ID \
  --data-urlencode "name=Ada Lovelace" \
  --data-urlencode "email=ada@example.com" \
  --data-urlencode "message=Hello from the API!"
```

The submission endpoint accepts `application/x-www-form-urlencoded` or `multipart/form-data` (required for file uploads). JSON bodies are not supported. See [Form Configuration](/docs/form-configuration) for field types and validation rules.

### List your forms (requires API key)

```bash
curl https://api.staticform.app/api/v1/forms?pageNumber=1&pageSize=25 \
  -H "X-API-Key: $STATICFORM_API_KEY"
```

### List submissions for a form

```bash
curl https://api.staticform.app/api/v1/forms/YOUR_FORM_ID/submissions \
  -H "X-API-Key: $STATICFORM_API_KEY"
```

### Export submissions as JSON

```bash
curl https://api.staticform.app/api/v1/forms/YOUR_FORM_ID/submissions/export/json \
  -H "X-API-Key: $STATICFORM_API_KEY" \
  -o submissions.json
```

### Create a form

```bash
curl -X POST https://api.staticform.app/api/v1/forms \
  -H "X-API-Key: $STATICFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "fields": [
      { "name": "email",   "type": "Text", "rule": "Email", "required": true },
      { "name": "message", "type": "Text", "rule": "None",  "required": true }
    ],
    "submitActions": [
      {
        "type": "SendEmailAction",
        "recipient": "you@example.com",
        "subject": "New submission from {{formName}}",
        "bodyTemplate": "{{submissionData}}",
        "format": "PlainText"
      }
    ]
  }'
```

## What You Can Do With the API

Anything you can do in the dashboard, you can do via the API. Common use cases:

- **Pull submissions** into your CRM, data warehouse, or internal tools
- **Create and update forms** programmatically (e.g., from infrastructure-as-code)
- **Sync submissions** to another system on a schedule
- **Build custom dashboards** or reporting on top of your form data
- **Automate cleanup**: delete old submissions, rotate forms, mark spam
- **Manage collaborators** on forms from your own admin tooling

The full list of endpoints (forms, submissions, submit actions, execution logs, collaborators, invitations, subscriptions, and user settings) is available in the [interactive API docs](https://api.staticform.app/docs).

## Rate Limits & Errors

- Validation failures return `400 Bad Request` with a `ProblemDetails` body listing each field and the reason.
- Authentication failures return `401 Unauthorized`; missing permissions return `403 Forbidden`.
- The API uses [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) for error responses.

## OpenAPI Specification

The raw OpenAPI JSON spec is available at:

```
https://api.staticform.app/openapi/v1.json
```

You can use this to:

- Generate client libraries in your language of choice (e.g., with [openapi-generator](https://openapi-generator.tech/))
- Import into Postman or Insomnia
- Integrate with any OpenAPI-compatible tooling
- Type-check API calls in TypeScript projects

## Need Help?

If you're building something with the API and get stuck, [contact us]({companyConfig.siteUrl}/#contact). We're happy to help.