# API: Projects

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/canvases` | Canvases you may see (yours, and those in projects you see), e.g. status=waiting_on_you | `records:read` |
| POST | `/v1/canvases` | Make a table or document canvas (optionally in a project) | `records:write` |
| GET | `/v1/canvases/:id` | A canvas with its content | `records:read` |
| PATCH | `/v1/canvases/:id` | Edit a canvas's title, content or status | `records:write` |
| GET | `/v1/projects` | Your projects and the team's shared ones | `records:read` |
| POST | `/v1/projects` | Start a project (private, or shared with the team) | `records:write` |
| GET | `/v1/projects/:id` | A project with the items you may see (each by its own permissions) and its canvases | `records:read` |
| PATCH | `/v1/projects/:id` | Rename, describe, share or archive a project (its owner) | `records:write` |
| POST | `/v1/projects/:id/items` | Add an item you can see: a conversation, list, document, record, run, canvas or person | `records:write` |
| DELETE | `/v1/projects/:id/items/:itemId` | Take an item out of a project (the item itself stays) | `records:write` |

## Examples

### GET /v1/canvases

Canvases you may see (yours, and those in projects you see), e.g. status=waiting_on_you

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

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

### POST /v1/canvases

Make a table or document canvas (optionally in a project)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/canvases`, {
  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/canvases/$ID

A canvas with its content

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

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

### PATCH /v1/canvases/$ID

Edit a canvas's title, content or status

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

```js
const res = await fetch(`https://api.closefinch.com/v1/canvases/${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();
```

### GET /v1/projects

Your projects and the team's shared ones

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

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

### POST /v1/projects

Start a project (private, or shared with the team)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/projects`, {
  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/projects/$ID

A project with the items you may see (each by its own permissions) and its canvases

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

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

### PATCH /v1/projects/$ID

Rename, describe, share or archive a project (its owner)

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

```js
const res = await fetch(`https://api.closefinch.com/v1/projects/${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/projects/$ID/items

Add an item you can see: a conversation, list, document, record, run, canvas or person

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

```js
const res = await fetch(`https://api.closefinch.com/v1/projects/${id}/items`, {
  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();
```

### DELETE /v1/projects/$ID/items/$ITEM_ID

Take an item out of a project (the item itself stays)

```bash
curl -s -X DELETE "https://api.closefinch.com/v1/projects/$ID/items/$ITEM_ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/projects/${id}/items/${itemId}`, {
  method: "DELETE",
  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).