API

Saved.io API docs

The API runs on the same domain as the app. Create an API token in Settings, then send it as a Bearer token to same-domain endpoints like /api/bookmarks.

Authentication

Generate keys from your account Settings. Tokens are shown once, so store the value after creating it. Send requests with an Authorization header:

Authorization: Bearer savedio-token-value

Scopes

Scope	Allows
`bookmarks:read`	List and view bookmarks.
`bookmarks:write`	Create, update, archive, and delete bookmarks.
`lists:read`	List and view bookmark lists.
`lists:write`	Create, update, and delete bookmark lists.

Bookmarks

GET /api/bookmarks List bookmarks.

POST /api/bookmarks Save a bookmark.

GET /api/bookmarks/{id} Read one bookmark.

PATCH /api/bookmarks/{id} Update title, URL, notes, or archive state.

DELETE /api/bookmarks/{id} Delete a bookmark.

Bookmark lists are paginated. Use per_page to request up to 100 bookmarks per page.

curl -H "Authorization: Bearer $SAVED_IO_TOKEN" \
  "https://saved.io/api/bookmarks?per_page=25"

Save a bookmark

Send url to save a bookmark. You can also send list_slug to place it in a list, title to set the title immediately, and notes for private notes and hashtags.

{
  "url": "https://example.com",
  "list_slug": "reading",
  "title": "Example",
  "notes": "Read later #research"
}

Update a bookmark

Send any of title, url, notes, or archived. Set archived to true to archive a bookmark, or false to restore it.

{
  "title": "Updated example",
  "notes": "Important reference #research",
  "archived": false
}

Lists

GET /api/lists List bookmark lists.

POST /api/lists Create a list.

GET /api/lists/{id} Read one list.

PATCH /api/lists/{id} Update list name or slug.

DELETE /api/lists/{id} Delete a list.

{
  "name": "Reading",
  "slug": "reading"
}

Bookmark response

{
  "id": 123,
  "list_id": 4,
  "list_slug": "reading",
  "title": "Example",
  "url": "https://example.com",
  "notes": "Read later #research",
  "tags": [{"id": 7, "slug": "research", "name": "Research"}],
  "favicon_url": null,
  "status": "ready",
  "archived_at": null,
  "created_at": "2026-06-03T00:00:00.000000Z",
  "updated_at": "2026-06-03T00:00:00.000000Z"
}

Errors

Status	Meaning
`401`	Missing or invalid Bearer token.
`402`	Payment is required to save more bookmarks or create lists.
`403`	The token is missing the required scope.
`404`	The resource does not exist or belongs to another account.
`422`	Validation failed. Check the returned field errors.