# Cofres e páginas

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

> Listar cofres, listar e ler páginas, criar, editar e mandar para a lixeira.



Todos os caminhos começam em `https://wire.ia.br/api/v1`. Os exemplos usam `$PAPER_TOKEN` e `$PAPER_CONTA` como variáveis de ambiente.

## Listar cofres [#listar-cofres]

```http
GET /vaults
```

Devolve só os cofres que o token alcança. Com token normal, só aparecem cofres sincronizados com o Google Drive. Com token seguro, aparece só a cópia dele.

```json
[
  { "id": "principal", "nome": "Meu caderno", "acesso": "editar", "copia": false },
  { "id": "cmg2k1x9a4tz", "nome": "Trabalho", "acesso": "ler", "copia": false }
]
```

O cofre principal sempre tem o id `principal`. Cópias para IA têm ids no formato `copia-` seguido de 16 caracteres.

## Listar páginas [#listar-páginas]

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

Sem `parent`, devolve todas as páginas e pastas do cofre. Com `parent={id}`, só as que estão dentro daquela página ou pasta. Com `parent=` vazio, só as da raiz.

```json
[
  { "id": "pa1k2m3n4o5p", "title": "Reunião de segunda", "parentId": null, "kind": "pagina", "updatedAt": "2026-10-01T14:03:11.000Z" },
  { "id": "pb7q8r9s0t1u", "title": "Projetos", "parentId": null, "kind": "pasta", "updatedAt": "2026-09-28T10:00:00.000Z" }
]
```

| Campo       | O que é                                                                                      |
| ----------- | -------------------------------------------------------------------------------------------- |
| `id`        | Id da página. É o mesmo no app, no Drive e na API.                                           |
| `title`     | Título.                                                                                      |
| `parentId`  | Página ou pasta onde ela está. `null` na raiz.                                               |
| `kind`      | `pagina` (tem texto) ou `pasta` (só agrupa).                                                 |
| `updatedAt` | Última mudança, em ISO 8601.                                                                 |
| `locked`    | `true` em páginas protegidas. Elas só aparecem na lista se o token puder ver o título delas. |

## Ler uma página [#ler-uma-página]

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

```json
{
  "id": "pa1k2m3n4o5p",
  "title": "Reunião de segunda",
  "parentId": null,
  "kind": "pagina",
  "updatedAt": "2026-10-01T14:03:11.000Z",
  "markdown": "## Pauta\n\n- [ ] Revisar orçamento @2026-10-06 10:00\n- [x] Mandar ata",
  "props": { "tags": "trabalho" }
}
```

Com `?format=md`, a resposta é só o texto em Markdown (`text/markdown`), começando pelo título. Bom para colar direto numa IA.

`props` traz as propriedades do frontmatter da página. O formato do Markdown está em [Formato das páginas](/api/formato-das-paginas).

Página protegida por senha responde `423`, sempre.

## Criar uma página ou pasta [#criar-uma-página-ou-pasta]

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

```json
{
  "title": "Ideias para o fim de semana",
  "markdown": "- Trilha no sábado\n- [ ] Comprar pão",
  "parentId": "pb7q8r9s0t1u",
  "kind": "pagina"
}
```

| Campo      | Obrigatório | Regras                                       |
| ---------- | ----------- | -------------------------------------------- |
| `title`    | Não         | Até 200 caracteres. Vazio vira "Sem título". |
| `markdown` | Não         | Até 1 MB. Ignorado em pastas.                |
| `parentId` | Não         | Id de uma página ou pasta do mesmo cofre.    |
| `kind`     | Não         | `pagina` (padrão) ou `pasta`.                |

Resposta:

```json
{ "id": "pc2v3w4x5y6z", "title": "Ideias para o fim de semana", "kind": "pagina" }
```

Precisa de permissão **Ler e editar** no cofre. A página aparece no app da pessoa na próxima sincronização.

## Editar uma página [#editar-uma-página]

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

Mande um ou mais destes campos:

| Campo      | O que faz                                               |
| ---------- | ------------------------------------------------------- |
| `title`    | Troca o título.                                         |
| `markdown` | Troca o texto inteiro.                                  |
| `append`   | Acrescenta texto no fim, depois de uma linha em branco. |

```json
{ "append": "## Atualização\n\nO orçamento foi aprovado." }
```

Prefira `append` sempre que der. Ele não apaga nada que a pessoa escreveu enquanto o seu programa trabalhava.

Pastas não têm texto: `PATCH` numa pasta com `markdown` ou `append` responde `400`.

## Mandar para a lixeira [#mandar-para-a-lixeira]

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

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

A página vai para a lixeira do Google Drive da pessoa, e dá para recuperar de lá. Em cópias para IA, a página fica marcada como apagada até a pessoa revisar.

## Quando o app vê as mudanças [#quando-o-app-vê-as-mudanças]

Com token normal, a mudança vai direto para o Google Drive. O app da pessoa traz na próxima sincronização, que acontece ao abrir o app, ao voltar para a aba e de tempos em tempos. Se a pessoa mexeu na mesma página no aparelho ao mesmo tempo, nada se perde: uma das versões vira uma cópia "(outra versão)".