# forms.app API

## Overview

The **forms.app API** gives you programmatic, read-only access to your forms and their
submissions. You can list all the forms in your account, fetch a specific form's complete
structure (questions, design settings, submission behaviour, thank-you pages), and page
through the answers your respondents have submitted.

## Authentication

Every request must be authenticated with exactly **one** of the two methods below.
Providing both in the same request is not allowed and will return `401 Unauthorized`.

### Option 1 — OAuth 2.0 Bearer Token

Obtain a JWT via the forms.app OAuth 2.0 flow and pass it in the `Authorization` header:

```
Authorization: Bearer <your_token>
```

### Option 2 — API Key

Pass your API key in the `X-Api-Key` header:

```
X-Api-Key: <your_api_key>
```

#### How to create an API key

1. Log in to [forms.app](https://forms.app).
2. Click your avatar in the top-right corner and open **Account Settings**.
3. Go to the **API Keys** tab.
4. Click **Create API Key**, enter a descriptive name, and confirm.
5. Copy the generated key immediately — it is shown **only once**.
6. Store it securely (e.g. in an environment variable or secret manager).

> You can create multiple keys (one per integration), and revoke any of them at any time
> from the same **API Keys** settings page.

> **Newly created or re-activated keys:** for up to ~30 seconds, a key whose validation
> recently failed may keep returning `401 Unauthorized` from a short-lived cache. If a key
> you just created or re-activated is rejected, wait ~30 seconds and retry.

## Response Envelope

All endpoints return a consistent JSON envelope:

**Success (`2xx`)**
```json
{
  "success": true,
  "data": { },
  "errors": []
}
```

**Error (`4xx` / `5xx`)**
```json
{
  "success": false,
  "data": null,
  "errors": [
    { "errorCode": 1001, "errorMessage": "Unauthorized" }
  ]
}
```

## Rate Limiting

Requests are rate-limited per API key / token (falling back to client IP when neither is
present). You may send up to **300 requests per 60-second window**. When the limit is
exceeded the API returns `429 Too Many Requests` with a `Retry-After` header indicating how
many seconds to wait before the window resets. Wait for that period and retry — do not spam
the endpoint in a tight loop.

A short-term burst limit also applies per endpoint (about **50 requests per second**, with a
burst allowance up to **100**). Spread requests out rather than firing them in a tight burst
to avoid transient `429` responses.


Version: 1.0.0
License: Proprietary

## Servers

```
https://api.forms.app
```

## Security

### BearerAuth

[object Object],[object Object],[object Object],[object Object]

Type: http
Scheme: bearer
Bearer Format: JWT

### ApiKeyAuth

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Type: apiKey
In: header
Name: X-Api-Key

## Download OpenAPI description

 - [forms.app API](https://developers.forms.app/_bundle/apis/index.yaml)

## Form

 - [GET /v1/form](https://developers.forms.app/apis/form/getuserforms.md): Returns a list of all forms that belong to the authenticated account. Each item in the returned array contains the form's unique identifier (`_id`) and its title. Use `_id` with the `GET /form/{id}` e
 - [GET /v1/form/{id}](https://developers.forms.app/apis/form/getformbyid.md): Returns the complete structure of a single form identified by its `_id`. The response includes everything needed to understand or reproduce the form: - **questions** — ordered list of all questions, e
## Answer

 - [GET /v1/form/{id}/answer/p/{pageNumber}](https://developers.forms.app/apis/answer/listformanswersbypage.md): Returns one page of submitted answers for the specified form. Because a form can accumulate a large number of submissions, results are delivered in pages. **Pagination flow:** 1. Call with `pageNumber
## Gateway

 - [GET /v1/health](https://developers.forms.app/apis/gateway/gatewayhealth.md): Returns the operational status of the API gateway (KrakenD) itself. Use this endpoint for infrastructure liveness probes and uptime monitoring. This is a KrakenD built-in endpoint — it reflects the ga