# List forms

`GET https://api.coach-platform.com/api/public/forms`

List forms (questionnaires) created by the coach. Returns each form's metadata only; the questions are NOT included here. To read the questions of a form, call GET /forms/{formId}. Use type=registration for the intake questionnaire trainees fill in when they join, and type=update for recurring check-in forms.

- Resource: Forms
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/get-forms
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `type` | string | No | Filter by form kind. "registration" is the join-time intake questionnaire; "update" is a recurring check-in form. Omit for both. Allowed values: `registration`, `update`. |
| `page` | integer | No | Page number (1-based, default 1) Minimum: `1`. |
| `limit` | integer | No | Number of items to return (default 25, max 500) Minimum: `1`. Maximum: `500`. |

## Responses

| Status | Description |
|---|---|
| `200` OK | Successful response |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object[] |   |
| `data[].id` | string |   |
| `data[].coach` | string |   |
| `data[].title` | string |   |
| `data[].description` | string |   |
| `data[].type` | string | registration = the join-time intake questionnaire. update = a recurring check-in form. Allowed values: `registration`, `update`. |
| `data[].isActive` | boolean |   |
| `data[].registrationOrder` | integer | Order this form is presented in during registration, when several registration forms exist. |
| `data[].openAt` | object | When and how often the form opens for trainees. |
| `data[].openAt.date` | string<date-time> |   |
| `data[].openAt.recurrence` | string | How often the form reopens. Allowed values: `weekly`, `bi-weekly`, `tri-weekly`, `monthly`. |
| `data[].openAt.openDays` | integer | How many days the form stays open once it opens. |
| `data[].target` | string | Who the form is shown to. byLabels targets trainees carrying at least one of targetLabels. Allowed values: `allTrainees`, `males`, `females`, `byLabels`. |
| `data[].targetLabels` | object[] | Labels this form targets. Only present when target is byLabels. |
| `data[].targetLabels[].id` | string |   |
| `data[].targetLabels[].text` | string |   |
| `data[].targetLabels[].color` | string |   |
| `data[].createdAt` | string<date-time> |   |
| `pagination` | object |   |
| `pagination.page` | number |   |
| `pagination.limit` | number |   |
| `pagination.total` | number \| null | Total number of matching items. null when the underlying source cannot report an exact count for this page; use hasMore to keep paging. |
| `pagination.hasMore` | boolean |   |
| `pagination.truncated` | boolean | Present and true when the result set exceeded the in-memory scan cap and was truncated. Narrow your filters to page through all items. |

Example:

```json
{
  "data": [
    {
      "id": "<string>",
      "coach": "<string>",
      "title": "<string>",
      "description": "<string>",
      "type": "registration",
      "isActive": true,
      "registrationOrder": 123,
      "openAt": {
        "date": "<date-time>",
        "recurrence": "weekly",
        "openDays": 123
      },
      "target": "allTrainees",
      "targetLabels": [
        {
          "id": "<string>",
          "text": "<string>",
          "color": "<string>"
        }
      ],
      "createdAt": "<date-time>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "hasMore": true,
    "truncated": true
  }
}
```

### Error responses 400, 401, 403, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request GET \
  --url 'https://api.coach-platform.com/api/public/forms' \
  --header 'Authorization: Bearer cp_live_...'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/forms', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer cp_live_...',
  },
});

const data = await response.json();
```

## Related endpoints

- [List registration form responses](https://www.coach-platform.com/docs/api/reference/get-forms-registration/index.md): `GET /api/public/forms/registration`. List submitted registration (intake) form responses across every registration form, newest first.
- [List check-in responses](https://www.coach-platform.com/docs/api/reference/get-updates/index.md): `GET /api/public/updates`. List submitted update (check-in) form responses across every update form, newest first.
- [Respond to a check-in](https://www.coach-platform.com/docs/api/reference/post-updates-update-id-respond/index.md): `POST /api/public/updates/{updateId}/respond`. Respond to a submitted check-in.
- [Get a form with its questions](https://www.coach-platform.com/docs/api/reference/get-forms-form-id/index.md): `GET /api/public/forms/{formId}`. Get one form including its full question set.
- [Get a form response](https://www.coach-platform.com/docs/api/reference/get-forms-form-id-response-response-id/index.md): `GET /api/public/forms/{formId}/response/{responseId}`. Get a single submitted form response with its answers.
- [List responses to a form](https://www.coach-platform.com/docs/api/reference/get-forms-form-id-responses/index.md): `GET /api/public/forms/{formId}/responses`. List submitted responses for a form, newest first.
- Previous: [Delete a meeting](https://www.coach-platform.com/docs/api/reference/delete-meetings-meeting-id/index.md): `DELETE /api/public/meetings/{meetingId}`. Delete a meeting permanently.
- Next: [List registration form responses](https://www.coach-platform.com/docs/api/reference/get-forms-registration/index.md): `GET /api/public/forms/registration`. List submitted registration (intake) form responses across every registration form, newest first.