# API: Lists

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/lists` | Saved lists (static membership or dynamic filters) | `records:read` |
| POST | `/v1/lists` | Create a list. Dynamic lists re-evaluate their filter every time they're read. | `records:write` |
| GET | `/v1/lists/:id` | Get one list with its member count | `records:read` |
| PATCH | `/v1/lists/:id` | Rename, change the filter, archive or restore a list | `records:write` |
| POST | `/v1/lists/:id/members` | Add or remove records on a static list (a record can be on many lists) | `records:write` |
| GET | `/v1/lists/:id/records` | Records on a list (dynamic lists evaluate their filter now) | `records:read` |
| GET | `/v1/lists/schema` | JSON Schemas for list create and update bodies (including the dynamic filter grammar) | `records:read` |

## Examples

### GET /v1/lists

Saved lists (static membership or dynamic filters)

```bash
curl -s "https://api.closefinch.com/v1/lists" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/lists`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/lists

Create a list. Dynamic lists re-evaluate their filter every time they're read.

```bash
curl -s -X POST "https://api.closefinch.com/v1/lists" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/lists`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/lists/$ID

Get one list with its member count

```bash
curl -s "https://api.closefinch.com/v1/lists/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/lists/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### PATCH /v1/lists/$ID

Rename, change the filter, archive or restore a list

```bash
curl -s -X PATCH "https://api.closefinch.com/v1/lists/$ID" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/lists/${id}`, {
  method: "PATCH",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/lists/$ID/members

Add or remove records on a static list (a record can be on many lists)

```bash
curl -s -X POST "https://api.closefinch.com/v1/lists/$ID/members" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/lists/${id}/members`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/lists/$ID/records

Records on a list (dynamic lists evaluate their filter now)

```bash
curl -s "https://api.closefinch.com/v1/lists/$ID/records" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/lists/${id}/records`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/lists/schema

JSON Schemas for list create and update bodies (including the dynamic filter grammar)

```bash
curl -s "https://api.closefinch.com/v1/lists/schema" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/lists/schema`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).