# Pages and collections: API examples

These examples use the same call as the [⚡ API quickstart](https://docs.wrightdesk.com/build-with-the-api/api-quickstart): a `POST` of a JSON-RPC `tools/call` message. Only the tool name and its `arguments` change. `NOTEMAKER_URL` and `NOTEMAKER_TOKEN` are set as in the quickstart. The answer text is in `result.content[0].text`.

## List and search pages

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages","arguments":{"action":"list","limit":20}}}'
```

Narrow a list with `collection_id`, `parent_id` or `depth`. Search looks in titles and text, every word must match:

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages","arguments":{"action":"search","query":"quarterly plan"}}}'
```

```text
- Hello from the API (id: cmvp00soi0000qe7dmm9pb073)
  Created with curl.
```

## Read a page

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages","arguments":{"action":"get","page_id":"cmvp00soi0000qe7dmm9pb073"}}}'
```

The body comes back as Markdown, after a short header:

```text
# Hello from the API

- id: cmvp00soi0000qe7dmm9pb073
- workspace: My workspace (your-workspace)
- visibility: private
- width: normal

---
Created with curl.
```

`page_id` also accepts a page address or public link.

## Create, update and append

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages_write","arguments":{"action":"create","title":"Meeting notes","content_markdown":"## Agenda\n\n- [ ] Review the plan","collection_id":"cmvkjzyjm00047d1u21g2mfct"}}}'
```

Update replaces the content by default. Use `"mode":"append"` to add to the end, and leave a field out to keep it as it is:

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages_write","arguments":{"action":"update","page_id":"cmvp00soi0000qe7dmm9pb073","content_markdown":"More text.","mode":"append"}}}'
```

```text
Updated page cmvp00soi0000qe7dmm9pb073.
```

## Move, share and trash

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages_write","arguments":{"action":"set_visibility","page_id":"cmvp00soi0000qe7dmm9pb073","visibility":"WORKSPACE","level":"VIEW"}}}'
```

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages_write","arguments":{"action":"delete","page_id":"cmvp00soi0000qe7dmm9pb073"}}}'
```

```text
Moved page cmvp00soi0000qe7dmm9pb073 to trash.
```

A deleted page can be brought back with the `trash` tool, see the Agents, trash and errors examples in this section.

## Collections

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"collections","arguments":{"action":"list"}}}'
```

```text
- Handbook  (id: cmvkjzyjm00047d1u21g2mfct, private, 2 pages)
```

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"collections_write","arguments":{"action":"create","name":"API examples","icon":"🧪"}}}'
```

```text
Created collection "API examples" (id: cmvp032h60007qe7dx5vtgjbr).
```

## Use a template

```bash
curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pages","arguments":{"action":"templates","query":"meeting"}}}'
```

Then pass the id as `template_id` to `pages_write` with `"action":"create"`.