# Vaults and pages

Source: https://wire.ia.br/documentation/en/api/cofres-e-paginas

> List vaults, list and read pages, create, edit and send to the trash.



All paths start at `https://wire.ia.br/api/v1`. The examples use `$PAPER_TOKEN` and `$PAPER_ACCOUNT` as environment variables.

## List vaults [#list-vaults]

```http
GET /vaults
```

Returns only the vaults the token reaches. With a regular token, only vaults synced with Google Drive show up. With a secure token, only its own copy shows up.

```json
[
  { "id": "principal", "nome": "My notebook", "acesso": "editar", "copia": false },
  { "id": "cmg2k1x9a4tz", "nome": "Work", "acesso": "ler", "copia": false }
]
```

The main vault always has the id `principal`. Copies for AI have ids in the format `copia-` followed by 16 characters.

## List pages [#list-pages]

```http
GET /vaults/{vault}/pages
GET /vaults/{vault}/pages?parent={id}
GET /vaults/{vault}/pages?parent=
```

Without `parent`, it returns all pages and folders in the vault. With `parent={id}`, only those inside that page or folder. With an empty `parent=`, only those at the root.

```json
[
  { "id": "pa1k2m3n4o5p", "title": "Monday meeting", "parentId": null, "kind": "pagina", "updatedAt": "2026-10-01T14:03:11.000Z" },
  { "id": "pb7q8r9s0t1u", "title": "Projects", "parentId": null, "kind": "pasta", "updatedAt": "2026-09-28T10:00:00.000Z" }
]
```

| Field       | What it is                                                                                |
| ----------- | ----------------------------------------------------------------------------------------- |
| `id`        | Page id. The same in the app, in Drive and in the API.                                    |
| `title`     | Title.                                                                                    |
| `parentId`  | Page or folder it sits in. `null` at the root.                                            |
| `kind`      | `pagina` (has text) or `pasta` (folder, only groups).                                     |
| `updatedAt` | Last change, in ISO 8601.                                                                 |
| `locked`    | `true` on protected pages. They only appear in the list if the token may see their title. |

## Read a page [#read-a-page]

```http
GET /vaults/{vault}/pages/{id}
GET /vaults/{vault}/pages/{id}?format=md
```

```json
{
  "id": "pa1k2m3n4o5p",
  "title": "Monday meeting",
  "parentId": null,
  "kind": "pagina",
  "updatedAt": "2026-10-01T14:03:11.000Z",
  "markdown": "## Agenda\n\n- [ ] Review budget @2026-10-06 10:00\n- [x] Send minutes",
  "props": { "tags": "work" }
}
```

With `?format=md`, the response is just the Markdown text (`text/markdown`), starting with the title. Good for pasting straight into an AI.

`props` holds the page's frontmatter properties. The Markdown format is in [Page format](/en/api/formato-das-paginas).

A page protected by a password always answers `423`.

## Create a page or folder [#create-a-page-or-folder]

```http
POST /vaults/{vault}/pages
Content-Type: application/json
```

```json
{
  "title": "Weekend ideas",
  "markdown": "- Hike on Saturday\n- [ ] Buy bread",
  "parentId": "pb7q8r9s0t1u",
  "kind": "pagina"
}
```

| Field      | Required | Rules                                           |
| ---------- | -------- | ----------------------------------------------- |
| `title`    | No       | Up to 200 characters. Empty becomes "Untitled". |
| `markdown` | No       | Up to 1 MB. Ignored for folders.                |
| `parentId` | No       | Id of a page or folder in the same vault.       |
| `kind`     | No       | `pagina` (default) or `pasta`.                  |

Response:

```json
{ "id": "pc2v3w4x5y6z", "title": "Weekend ideas", "kind": "pagina" }
```

Needs the **Read and edit** permission on the vault. The page shows up in the person's app on the next sync.

## Edit a page [#edit-a-page]

```http
PATCH /vaults/{vault}/pages/{id}
Content-Type: application/json
```

Send one or more of these fields:

| Field      | What it does                              |
| ---------- | ----------------------------------------- |
| `title`    | Changes the title.                        |
| `markdown` | Replaces the whole text.                  |
| `append`   | Adds text at the end, after a blank line. |

```json
{ "append": "## Update\n\nThe budget was approved." }
```

Prefer `append` whenever you can. It doesn't erase anything the person wrote while your program was working.

Folders have no text: a `PATCH` on a folder with `markdown` or `append` answers `400`.

## Send to the trash [#send-to-the-trash]

```http
DELETE /vaults/{vault}/pages/{id}
```

```json
{ "ok": true, "lixeira": true }
```

The page goes to the trash of the person's Google Drive, and can be recovered from there. In copies for AI, the page is marked as deleted until the person reviews it.

## When the app sees the changes [#when-the-app-sees-the-changes]

With a regular token, the change goes straight to Google Drive. The person's app picks it up on the next sync, which happens when opening the app, when returning to the tab and from time to time. If the person touched the same page on their device at the same time, nothing is lost: one of the versions becomes a copy "(other version)".