# Forms API

Manage your forms programmatically.

**Base URL:** `https://forms.wtf/api/v1`\
**Auth:** `Authorization: Bearer YOUR_API_KEY`

***

## List forms

```
GET /forms
```

Returns all forms owned by the authenticated user (personal + team forms).

**Response:**

```json
{
  "forms": [
    {
      "id": "clxyz...",
      "title": "DAO Contributor Survey",
      "slug": "dao-survey",
      "published": true,
      "responseCount": 142,
      "createdAt": "2026-03-01T10:00:00.000Z",
      "updatedAt": "2026-04-01T09:00:00.000Z"
    }
  ]
}
```

***

## Get a form

```
GET /forms/:id
```

Returns full form details including questions and gate rules.

**Response:**

```json
{
  "id": "clxyz...",
  "title": "DAO Contributor Survey",
  "slug": "dao-survey",
  "published": true,
  "questions": [
    {
      "id": "q_abc",
      "type": "SHORT_TEXT",
      "label": "What is your name?",
      "required": true,
      "order": 0
    }
  ],
  "gateRules": []
}
```

***

## Get form responses

```
GET /forms/:id/responses
```

Returns all responses for the form, with answers.

**Query parameters:**

| Param    | Type     | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| `limit`  | number   | Max responses to return (default: 100, max: 1000) |
| `offset` | number   | Pagination offset                                 |
| `since`  | ISO date | Only responses submitted after this date          |

**Response:**

```json
{
  "responses": [
    {
      "id": "clresponse...",
      "walletAddress": "0xabc...def",
      "ensName": "vitalik.eth",
      "submittedAt": "2026-04-01T14:32:00.000Z",
      "durationSeconds": 87,
      "answers": [
        {
          "questionId": "q_abc",
          "questionLabel": "What is your name?",
          "value": "Alice"
        }
      ]
    }
  ],
  "total": 142,
  "hasMore": true
}
```

***

## Export responses

```
GET /forms/:id/export
```

**Query parameters:**

| Param    | Values                  | Description                                     |
| -------- | ----------------------- | ----------------------------------------------- |
| `format` | `csv`, `json`, `merkle` | Export format (`merkle` requires Business plan) |

Returns the file as a download.

***

## Examples

### Fetch all responses and process them

```javascript
const API_KEY = 'your_api_key';
const FORM_ID = 'clxyz...';

async function getAllResponses() {
  let offset = 0;
  const allResponses = [];

  while (true) {
    const res = await fetch(
      `https://forms.wtf/api/v1/forms/${FORM_ID}/responses?limit=100&offset=${offset}`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );
    const { responses, hasMore } = await res.json();
    allResponses.push(...responses);
    if (!hasMore) break;
    offset += 100;
  }

  return allResponses;
}
```

### Get new responses since yesterday

```javascript
const yesterday = new Date(Date.now() - 86400000).toISOString();

const res = await fetch(
  `https://forms.wtf/api/v1/forms/${FORM_ID}/responses?since=${yesterday}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { responses } = await res.json();
```

### Export as CSV

```bash
curl "https://forms.wtf/api/v1/forms/clxyz.../export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output responses.csv
```