> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dexi.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Save Bookmark

> Save a page into your Dexi workspace

The one endpoint personal API tokens authenticate — the write-only capture path used by the iOS share-sheet Shortcut. The saved page becomes a bookmark-backed note: searchable (full-text and semantic), taggable, and connected like everything else in your workspace.

<ParamField body="url" type="string" required>
  The page URL. Must start with `http://` or `https://` — anything else is rejected with `422`.
</ParamField>

<ParamField body="title" type="string">
  Page title. Optional; Dexi falls back to the URL when absent.
</ParamField>

<ParamField body="selection" type="string">
  Selected text to save with the page — appended to the note body.
</ParamField>

<ParamField body="append" type="boolean" default="false">
  Explicitly request append behavior when the URL is already saved.
</ParamField>

Saving a **new URL** creates a bookmark and its note. Saving a URL **already in your workspace** doesn't duplicate it — the existing note is reused, and any `selection` is appended to it (so repeatedly sharing the same article accumulates your highlights on one note).

```bash Example request theme={null}
curl -X POST https://api.dexi.net/api/v1/bookmarks/save \
  -H "Authorization: Bearer dxi_2f7c1a9e4b8d3f6a0c5e9b2d7f4a8c1e3b6d9f2a" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://arxiv.org/abs/1706.03762",
    "title": "Attention Is All You Need",
    "selection": "The dominant sequence transduction models are based on complex recurrent networks."
  }'
```

```json Example response theme={null}
{
  "bookmark": {
    "id": "7c1f3e58-2ab4-4b6f-9d21-8f4e5c6a7b90",
    "note_id": "2982e9b4-19fe-40fd-9a69-e23d45e53b13",
    "title": "Attention Is All You Need",
    "url": "https://arxiv.org/abs/1706.03762",
    "icon": "https://api.dexi.net/media/icons/arxiv.org.png",
    "created": "2026-08-05T14:20:00+00:00",
    "updated": "2026-08-05T14:20:00+00:00"
  },
  "note_id": "2982e9b4-19fe-40fd-9a69-e23d45e53b13",
  "is_new_bookmark": true,
  "selection_appended": false
}
```

`icon` is `null` until the favicon fetch completes in the background.

## Errors

| Status | Meaning                                                    |
| ------ | ---------------------------------------------------------- |
| `401`  | Missing, revoked, or malformed token                       |
| `402`  | Free-plan note limit reached — machine-readable body below |
| `422`  | Invalid body (e.g. non-http(s) `url`)                      |

```json 402 response theme={null}
{
  "detail": {
    "code": "note_limit",
    "message": "You've reached the free plan limit of 1,000 notes.",
    "used": 1000,
    "limit": 1000
  }
}
```

## iOS Shortcut

The share-sheet Shortcut is a single **Get Contents of URL** action posting this shape with your token in the `Authorization` header. Step-by-step setup: [Automate capture with API tokens](https://dexi.net/kb/save-with-api-tokens).