---
title: REST API quickstart
description: Read your forms and completed responses with the Finerlise REST API.
icon: braces
search:
  keywords: [api, rest, curl, endpoints, responses api, forms api]
---

**Base URL:** `https://finerlise.com/api/v1`. All requests need an `Authorization: Bearer …` header. See [Authentication](/developers/authentication-api-keys).

## 1. Check your token

```bash
curl https://finerlise.com/api/v1/me \
  -H "Authorization: Bearer $FINERLISE_API_KEY"
```

```json
{
  "workspace": { "id": "…", "name": "Acme", "slug": "acme" },
  "user": null,
  "scope": "responses:read"
}
```

## 2. List a form's latest responses

```bash curl
curl "https://finerlise.com/api/v1/forms/$FORM_ID/responses?limit=25" \
  -H "Authorization: Bearer $FINERLISE_API_KEY"
```

```js JavaScript
const res = await fetch(
  `https://finerlise.com/api/v1/forms/${formId}/responses?limit=25`,
  { headers: { Authorization: `Bearer ${process.env.FINERLISE_API_KEY}` } }
);
const { data } = await res.json();
```

```python Python
import os, requests

res = requests.get(
    f"https://finerlise.com/api/v1/forms/{form_id}/responses",
    params={"limit": 25},
    headers={"Authorization": f"Bearer {os.environ['FINERLISE_API_KEY']}"},
)
data = res.json()["data"]
```

Returns the most recent **completed** responses, newest first. `limit` is 1–25 (default 10). Each item has the same shape as the `data` object of a [`response.completed` webhook](/developers/webhooks-reference).

## 3. Get one response

```bash
curl https://finerlise.com/api/v1/responses/$RESPONSE_ID \
  -H "Authorization: Bearer $FINERLISE_API_KEY"
```

## Endpoints

| Method | Path | Scope | Description |
| --- | --- | --- | --- |
| `GET` | `/me` | any | The workspace (and user, for OAuth) the token acts as. |
| `GET` | `/forms` | `forms:read` | The workspace's forms, most recently updated first. Paginate with `limit` (1–100, default 50) and `cursor` (the `nextCursor` from the previous page). |
| `GET` | `/forms/{formId}/responses` | `responses:read` | Latest completed responses for a form. |
| `GET` | `/responses/{responseId}` | `responses:read` | One completed response. |
| `POST` | `/hooks` | `hooks:write` | Subscribe a URL to new responses (OAuth apps). |
| `DELETE` | `/hooks/{hookId}` | `hooks:write` | Remove a subscription. |

IDs are UUIDs. For full schemas, see the [API reference](/reference).

:::tip[Don't poll] To react to new responses, use [webhooks](/integrations/webhooks) instead of calling the API repeatedly. Use the API to fetch a response when you have its ID, or to catch up. :::