API & API Keys

Overview

The StashSync REST API (https://api.stashsync.app/v1/*) gives programmatic access to all your notes, bookmarks, stashes, and tags. It's designed for automation tools like n8n and Zapier, custom scripts, and third-party integrations.

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Two token types are accepted:

For external integrations, always use an API key. The raw key is shown once at creation and cannot be retrieved again.

Rate limit: 120 requests per minute per API key.

Creating an API key

1. Open Settings in the sidebar.
2. Go to the API Keys tab.
3. Click Create API key and enter a name (e.g. n8n, my-script).
4. Copy the key shown — it starts with ss_live_ and is displayed only once.
5. Store it somewhere safe (a password manager or secrets vault).

You can have up to 10 active API keys per account. To revoke a key, click the trash icon next to it — revocation is immediate.

REST API reference

Notes

The note object

Each Tag in the tags array:

GET /v1/notes

List notes belonging to the authenticated user. Returns active (non-trashed) notes by default.

Query parameters

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Meeting notes",
      "content": "## Agenda\n- Item 1\n- Item 2",
      "stashId": "e5f6a7b8-c9d0-1234-efab-567890abcdef",
      "pinned": false,
      "trashedAt": null,
      "tags": [
        { "id": "t1b2c3d4-...", "name": "work", "color": "#3b82f6" }
      ],
      "createdAt": 1746700000000,
      "updatedAt": 1746700000000
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Example

# All active notes
curl https://api.stashsync.app/v1/notes \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

# Notes in a specific stash, paginated
curl "https://api.stashsync.app/v1/notes?stash_id=e5f6a7b8-...&limit=20&offset=40" \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

# Trashed notes only
curl "https://api.stashsync.app/v1/notes?trashed=true" \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

GET /v1/notes/:id

Get a single note by ID.

Path parameters

Response — the note object

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Meeting notes",
  "content": "## Agenda\n- Item 1\n- Item 2",
  "stashId": null,
  "pinned": false,
  "trashedAt": null,
  "tags": [],
  "createdAt": 1746700000000,
  "updatedAt": 1746700000000
}

Errors

Example

curl https://api.stashsync.app/v1/notes/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/notes

Create a new note.

Request body

Response 201 Created — the note object

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Meeting notes",
  "content": "## Agenda\n- Item 1\n- Item 2",
  "stashId": null,
  "pinned": false,
  "trashedAt": null,
  "tags": [],
  "createdAt": 1746700000000,
  "updatedAt": 1746700000000
}

Errors

Example

curl -X POST https://api.stashsync.app/v1/notes \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting notes",
    "content": "## Agenda\n- Item 1\n- Item 2",
    "stashId": "e5f6a7b8-c9d0-1234-efab-567890abcdef",
    "tagIds": ["t1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

PATCH /v1/notes/:id

Update one or more fields on an existing note. Only the fields you include are changed — omitted fields are left as-is.

Path parameters

Request body — all fields optional

updatedAt is automatically set to the current timestamp on every successful update.

Response — the updated note object

Errors

Example

# Pin the note and move it to a different stash
curl -X PATCH https://api.stashsync.app/v1/notes/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pinned": true,
    "stashId": "e5f6a7b8-c9d0-1234-efab-567890abcdef"
  }'

# Update only the title
curl -X PATCH https://api.stashsync.app/v1/notes/a1b2c3d4-... \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated title" }'

DELETE /v1/notes/:id

Move a note to trash (soft-delete). The note is not permanently removed and can be restored at any time.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X DELETE https://api.stashsync.app/v1/notes/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/notes/:id/restore

Restore a trashed note, making it active again.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X POST https://api.stashsync.app/v1/notes/a1b2c3d4-e5f6-7890-abcd-ef1234567890/restore \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

Bookmarks

The bookmark object

Each Tag in the tags array:

GET /v1/bookmarks

List bookmarks belonging to the authenticated user. Returns active (non-trashed) bookmarks by default, ordered by updatedAt descending.

Query parameters

Response

{
  "data": [
    {
      "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "url": "https://example.com/article",
      "title": "An Interesting Article",
      "description": "A summary of the article content.",
      "imageUrl": "https://example.com/og-image.png",
      "stashId": "e5f6a7b8-c9d0-1234-efab-567890abcdef",
      "pinned": false,
      "trashedAt": null,
      "tags": [
        { "id": "t1b2c3d4-...", "name": "reading", "color": "#10b981" }
      ],
      "createdAt": 1746700000000,
      "updatedAt": 1746700000000
    }
  ],
  "total": 18,
  "limit": 50,
  "offset": 0
}

Example

# All active bookmarks
curl https://api.stashsync.app/v1/bookmarks \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

# Bookmarks in a specific stash
curl "https://api.stashsync.app/v1/bookmarks?stash_id=e5f6a7b8-...&limit=20" \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

# Trashed bookmarks only
curl "https://api.stashsync.app/v1/bookmarks?trashed=true" \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

GET /v1/bookmarks/:id

Get a single bookmark by ID.

Path parameters

Response — the bookmark object

{
  "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "url": "https://example.com/article",
  "title": "An Interesting Article",
  "description": "A summary of the article content.",
  "imageUrl": "https://example.com/og-image.png",
  "stashId": null,
  "pinned": false,
  "trashedAt": null,
  "tags": [],
  "createdAt": 1746700000000,
  "updatedAt": 1746700000000
}

Errors

Example

curl https://api.stashsync.app/v1/bookmarks/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/bookmarks

Save a new bookmark.

Request body

Response 201 Created — the bookmark object

{
  "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "url": "https://example.com/article",
  "title": "An Interesting Article",
  "description": "A summary of the article content.",
  "imageUrl": null,
  "stashId": null,
  "pinned": false,
  "trashedAt": null,
  "tags": [],
  "createdAt": 1746700000000,
  "updatedAt": 1746700000000
}

Errors

Example

# Minimal — URL only
curl -X POST https://api.stashsync.app/v1/bookmarks \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/article" }'

# With metadata, stash, and tags
curl -X POST https://api.stashsync.app/v1/bookmarks \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "title": "An Interesting Article",
    "description": "A summary of the article content.",
    "imageUrl": "https://example.com/og-image.png",
    "stashId": "e5f6a7b8-c9d0-1234-efab-567890abcdef",
    "tagIds": ["t1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

PATCH /v1/bookmarks/:id

Update one or more fields on an existing bookmark. Only the fields you include are changed — omitted fields are left as-is.

Path parameters

Request body — all fields optional

updatedAt is automatically set to the current timestamp on every successful update.

Response — the updated bookmark object

Errors

Example

# Update the title and pin the bookmark
curl -X PATCH https://api.stashsync.app/v1/bookmarks/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "pinned": true
  }'

# Clear the preview image and remove from stash
curl -X PATCH https://api.stashsync.app/v1/bookmarks/b1c2d3e4-... \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "imageUrl": null, "stashId": null }'

DELETE /v1/bookmarks/:id

Move a bookmark to trash (soft-delete). The bookmark is not permanently removed and can be restored at any time.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X DELETE https://api.stashsync.app/v1/bookmarks/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/bookmarks/:id/restore

Restore a trashed bookmark, making it active again.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X POST https://api.stashsync.app/v1/bookmarks/b1c2d3e4-f5a6-7890-bcde-f12345678901/restore \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

Stashes

The stash object

GET /v1/stashes

List all stashes belonging to the authenticated user. Returns only active (non-trashed) stashes.

Query parameters

Response

{
  "data": [
    {
      "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Work",
      "color": "#3b82f6",
      "createdAt": 1746700000000
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}

Example

curl https://api.stashsync.app/v1/stashes \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

GET /v1/stashes/:id

Get a single stash by ID.

Path parameters

Response — the stash object

{
  "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Work",
  "color": "#3b82f6",
  "createdAt": 1746700000000
}

Errors

Example

curl https://api.stashsync.app/v1/stashes/s1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/stashes

Create a new stash.

Request body

Response 201 Created — the stash object

{
  "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Work",
  "color": "#3b82f6",
  "createdAt": 1746700000000
}

Errors

Example

curl -X POST https://api.stashsync.app/v1/stashes \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Work", "color": "#3b82f6" }'

PATCH /v1/stashes/:id

Update one or more fields on an existing stash. Only the fields you include are changed.

Path parameters

Request body — all fields optional

Response — the updated stash object

Errors

Example

# Rename and recolor
curl -X PATCH https://api.stashsync.app/v1/stashes/s1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Work Projects", "color": "#10b981" }'

# Clear the color
curl -X PATCH https://api.stashsync.app/v1/stashes/s1a2b3c4-... \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "color": null }'

DELETE /v1/stashes/:id

Move a stash to trash (soft-delete). Items inside the stash are not deleted — they lose their stash assignment and return to the main view.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X DELETE https://api.stashsync.app/v1/stashes/s1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/stashes/:id/restore

Restore a trashed stash, making it active again.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X POST https://api.stashsync.app/v1/stashes/s1a2b3c4-d5e6-7890-abcd-ef1234567890/restore \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

GET /v1/stashes/:id/items

List notes and bookmarks that belong to a stash. Only active (non-trashed) items are returned.

Path parameters

Query parameters

Response

Each item in data is a lightweight summary — use GET /v1/notes/:id or GET /v1/bookmarks/:id to fetch full details.

{
  "data": [
    {
      "type": "note",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Meeting notes",
      "updatedAt": 1746700000000
    },
    {
      "type": "bookmark",
      "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "title": "An Interesting Article",
      "updatedAt": 1746699000000
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Errors

Example

curl https://api.stashsync.app/v1/stashes/s1a2b3c4-d5e6-7890-abcd-ef1234567890/items \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

Tags

The tag object

GET /v1/tags

List all tags belonging to the authenticated user. Returns all active (non-trashed) tags sorted alphabetically by name. This endpoint returns all tags without pagination.

Response

{
  "data": [
    { "id": "t1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "reading", "color": "#10b981" },
    { "id": "t2c3d4e5-f6a7-8901-bcde-f12345678902", "name": "work", "color": "#3b82f6" }
  ],
  "total": 2
}

Example

curl https://api.stashsync.app/v1/tags \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

GET /v1/tags/:id

Get a single tag by ID.

Path parameters

Response — the tag object

{
  "id": "t1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "reading",
  "color": "#10b981"
}

Errors

Example

curl https://api.stashsync.app/v1/tags/t1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/tags

Create a new tag.

Request body

Response 201 Created — the tag object

{
  "id": "t1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "reading",
  "color": "#10b981"
}

Errors

Example

curl -X POST https://api.stashsync.app/v1/tags \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "reading", "color": "#10b981" }'

PATCH /v1/tags/:id

Update one or more fields on an existing tag. Only the fields you include are changed.

Path parameters

Request body — all fields optional

Response — the updated tag object

Errors

Example

# Rename the tag
curl -X PATCH https://api.stashsync.app/v1/tags/t1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "to-read" }'

# Change the color
curl -X PATCH https://api.stashsync.app/v1/tags/t1b2c3d4-... \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "color": "#f59e0b" }'

DELETE /v1/tags/:id

Move a tag to trash (soft-delete). Items that use this tag are not deleted — they simply lose this tag association.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X DELETE https://api.stashsync.app/v1/tags/t1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

POST /v1/tags/:id/restore

Restore a trashed tag, making it active again.

Path parameters

Response

{ "ok": true }

Errors

Example

curl -X POST https://api.stashsync.app/v1/tags/t1b2c3d4-e5f6-7890-abcd-ef1234567890/restore \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

GET /v1/tags/:id/items

List notes and bookmarks that have this tag applied. Only active (non-trashed) items are returned, ordered by most recently updated first.

Path parameters

Query parameters

Response

{
  "data": [
    {
      "type": "note",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Reading list",
      "updatedAt": 1746700000000
    },
    {
      "type": "bookmark",
      "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "title": "An Interesting Article",
      "updatedAt": 1746699000000
    }
  ],
  "total": 7,
  "limit": 50,
  "offset": 0
}

Errors

Example

curl https://api.stashsync.app/v1/tags/t1b2c3d4-e5f6-7890-abcd-ef1234567890/items \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

Search

GET /v1/search

Search across all your notes, bookmarks, and files using full-text search. Results are ranked by relevance and capped at 20. Trashed and deleted items are always excluded.

Query parameters

Response — a flat array of up to 20 results (no pagination wrapper)

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "note",
    "title": "Meeting notes",
    "snippet": "…discussed the <mark>quarterly</mark> review and next steps…"
  },
  {
    "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
    "type": "bookmark",
    "title": "Q4 Planning Article",
    "snippet": "…a guide to <mark>quarterly</mark> planning for remote teams…"
  }
]

Search scope

Errors

Example

curl "https://api.stashsync.app/v1/search?q=quarterly+review" \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

Pagination

List endpoints support limit (default 50, max 100) and offset for cursor-style pagination:

curl "https://api.stashsync.app/v1/notes?limit=20&offset=40" \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

The response always includes a total field — the count of all matching records before pagination — so you can calculate how many pages remain.

Filtering

Combine query parameters to narrow results:

# Notes in a specific stash tagged with a specific tag
curl "https://api.stashsync.app/v1/notes?stash_id=<stash_id>&tag_id=<tag_id>" \
  -H "Authorization: Bearer ss_live_YOUR_KEY"