Saved.io API

Base URL

https://saved.io/api

Machine-readable docs

GET https://saved.io/api/openapi.json

Authentication

Saved.io supports two ways to authenticate API requests.

Personal API tokens

Use personal API tokens for your own scripts, automations and private agents.

Authorization: Bearer SAVED_IO_TOKEN

Create and revoke tokens from the Developer page.

OAuth

Use OAuth for apps that connect other Saved.io accounts.

Authorization endpoint: https://saved.io/oauth/authorize
Token endpoint: https://saved.io/oauth/token
PKCE: S256

Public clients should use OAuth authorization code with PKCE. Confidential clients can use a client secret.

Scopes

MCP

Saved.io provides a Model Context Protocol server for agents and MCP clients.

MCP endpoint

POST https://saved.io/mcp

Authentication

Use a Saved.io personal API token as a Bearer token.

Authorization: Bearer SAVED_IO_TOKEN

Create a token from the Developer page. Give it read, write, or both depending on what the agent should do.

Client support

Use this with any MCP client that supports streamable HTTP MCP servers and Bearer token authentication.

Tools

• Search and fetch bookmarks.
• Save, update, archive and restore bookmarks.
• List and create lists.

Agent-friendly URLs

Markdown guide: https://saved.io/api/guide.md
OpenAPI spec: https://saved.io/api/openapi.json
MCP OAuth metadata: https://saved.io/.well-known/oauth-protected-resource
OAuth metadata: https://saved.io/.well-known/oauth-authorization-server

Notes

• Agents should archive bookmarks unless the user clearly asks to permanently delete them.
• OAuth is available for apps that manage their own OAuth client setup.

Bookmarks

Save a bookmark

POST https://saved.io/api/bookmarks

curl -X POST "https://saved.io/api/bookmarks" \
  -H "Authorization: Bearer $SAVED_IO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","list":"Reading","notes":"Read later #research"}'

Notes

• #hashtags can be included in the notes field.
• A bookmark saved without a title will attempt to fetch the title in the background.
• Status is processing while Saved.io fetches metadata, then ready.

List bookmarks

GET https://saved.io/api/bookmarks

Notes

• archived defaults to active, so archived bookmarks are hidden unless requested.
• date_from and date_to should be date strings such as 2026-06-03.

Get one bookmark

GET https://saved.io/api/bookmarks/{id}

Update a bookmark

PATCH https://saved.io/api/bookmarks/{id}

Notes

• Send only the fields you want to update.
• Set archived to true to archive a bookmark.
• Set archived to false to restore an archived bookmark.

Delete a bookmark

DELETE https://saved.io/api/bookmarks/{id}

Notes

• This permanently deletes a bookmark.
• Use PATCH with archived set to true if you want to archive a bookmark instead.

Lists

Create a list

POST https://saved.io/api/lists

{"list":"Reading"}

List lists

GET https://saved.io/api/lists

Get one list

GET https://saved.io/api/lists/{id}

Update a list

PATCH https://saved.io/api/lists/{id}

{"list":"Reading Later"}

Delete a list

DELETE https://saved.io/api/lists/{id}

Notes

• Deleting a list keeps its bookmarks and clears their list.

Tags

Tags are generated from hashtags in bookmark notes.

List tags

GET https://saved.io/api/tags

Notes

• Tags are edited by updating bookmark notes.

Webhooks

You can set up a webhook to trigger whenever you save a bookmark.

Webhook endpoints must be public HTTPS URLs.

Headers

X-Saved-Event: bookmark.saved
X-Saved-Delivery: 7f8a4d1e-...
X-Saved-Timestamp: 1780000000
X-Saved-Signature: sha256=...

Payload

{
  "id": "7f8a4d1e-...",
  "event": "bookmark.saved",
  "created_at": "2026-06-03T00:00:00.000000Z",
  "data": {
    "bookmark": {
      "id": 123,
      "url": "https://example.com/article",
      "title": "Example article",
      "notes": "Read later #research",
      "status": "ready",
      "list": {"id": 4, "list": "Reading"},
      "tags": [{"id": 7, "tag": "Research"}],
      "created_at": "2026-06-03T00:00:00.000000Z"
    }
  }
}

Notes

• Webhooks are managed from the Developer page.
• The event name is bookmark.saved.
• To verify the signature, compute an HMAC SHA-256 digest of timestamp.raw_body.

Legacy compatibility

• Existing tokens with bookmarks:read, bookmarks:write, lists:read and lists:write still work.
• Existing integrations can still send list_slug, tag_slug and q.
• New integrations should use read, write, list, tag and search.

Errors

Validation errors return field-level messages:

{
  "message": "The url field is required.",
  "errors": {
    "url": ["The url field is required."]
  }
}

Rate limits

Authenticated API requests are limited to 120 requests per minute.