Appearance
REST reference
Every route answers under https://keepsake-gateway.onclick.workers.dev/api/v1 and needs a token, as Tokens and limits describes. This page is generated from the API's OpenAPI document, so it always matches what the API accepts.
List bookmarks, newest first
GET /bookmarks
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
cursor | string in query | no | |
limit | integer in query | no | 1 to 100; defaults to 50. |
tag | string in query | no | 1 to 64 characters. |
filter | one of all, readLater, failed, dead in query | no | Defaults to "all". |
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
items | array of object | yes | |
items[].id | string | yes | |
items[].url | string | yes | |
items[].title | string | yes | |
items[].notes | string | yes | |
items[].tags | array of string | yes | |
items[].readLater | boolean | yes | |
items[].isPublic | boolean | yes | |
items[].archiveStatus | one of pending, ready, partial, failed | yes | |
items[].archiveError | string | yes | |
items[].linkStatus | one of unknown, alive, redirected, dead | yes | |
items[].excerpt | string | yes | |
items[].createdAt | string | yes | An ISO 8601 timestamp in UTC. |
items[].updatedAt | string | yes | An ISO 8601 timestamp in UTC. |
nextCursor | string or null | yes |
Save a bookmark and archive its page
POST /bookmarks
Body
| Field | Type | Required | Notes |
|---|---|---|---|
url | string | yes | 1 to 2048 characters. |
title | string | no | 1 to 512 characters. |
notes | string | no | Up to 10000 characters. |
tags | array of string | no | Up to 32 items. |
readLater | boolean | no | Defaults to false. |
isPublic | boolean | no | Defaults to false. |
html | string | no | The page as the caller rendered it, archived instead of fetching the URL. 1 to 8388608 characters. |
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
id | string | yes | |
url | string | yes | |
title | string | yes | |
notes | string | yes | |
tags | array of string | yes | |
readLater | boolean | yes | |
isPublic | boolean | yes | |
archiveStatus | one of pending, ready, partial, failed | yes | |
archiveError | string | yes | |
linkStatus | one of unknown, alive, redirected, dead | yes | |
excerpt | string | yes | |
createdAt | string | yes | An ISO 8601 timestamp in UTC. |
updatedAt | string | yes | An ISO 8601 timestamp in UTC. |
Read a bookmark
GET /bookmarks/{id}
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
id | string in path | yes |
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
id | string | yes | |
url | string | yes | |
title | string | yes | |
notes | string | yes | |
tags | array of string | yes | |
readLater | boolean | yes | |
isPublic | boolean | yes | |
archiveStatus | one of pending, ready, partial, failed | yes | |
archiveError | string | yes | |
linkStatus | one of unknown, alive, redirected, dead | yes | |
excerpt | string | yes | |
createdAt | string | yes | An ISO 8601 timestamp in UTC. |
updatedAt | string | yes | An ISO 8601 timestamp in UTC. |
Edit a bookmark
PATCH /bookmarks/{id}
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
id | string in path | yes |
Body
| Field | Type | Required | Notes |
|---|---|---|---|
title | string | no | 1 to 512 characters. |
notes | string | no | Up to 10000 characters. |
tags | array of string | no | Up to 32 items. |
readLater | boolean | no | |
isPublic | boolean | no |
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
id | string | yes | |
url | string | yes | |
title | string | yes | |
notes | string | yes | |
tags | array of string | yes | |
readLater | boolean | yes | |
isPublic | boolean | yes | |
archiveStatus | one of pending, ready, partial, failed | yes | |
archiveError | string | yes | |
linkStatus | one of unknown, alive, redirected, dead | yes | |
excerpt | string | yes | |
createdAt | string | yes | An ISO 8601 timestamp in UTC. |
updatedAt | string | yes | An ISO 8601 timestamp in UTC. |
Delete a bookmark and its archive
DELETE /bookmarks/{id}
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
id | string in path | yes |
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
success | boolean | yes |
Read a bookmark's archived text
GET /bookmarks/{id}/archive
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
id | string in path | yes |
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
title | string | yes | |
byline | string | yes | |
siteName | string | yes | |
wordCount | integer | yes | |
markdown | string | yes | |
pdfUrl | string or null | yes | |
capturedAt | string | yes | An ISO 8601 timestamp in UTC. |
List tags with their bookmark counts
GET /tags
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
items | array of object | yes | |
items[].name | string | yes | |
items[].count | integer | yes |
Search titles, notes, tags, and archived text
GET /search
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
q | string in query | yes | Up to 256 characters. |
limit | integer in query | no | 1 to 50; defaults to 20. |
offset | integer in query | no | 0 to 1000; defaults to 0. |
Answer
| Field | Type | Always present | Notes |
|---|---|---|---|
items | array of object | yes | |
items[].bookmark | object | yes | |
items[].bookmark.id | string | yes | |
items[].bookmark.url | string | yes | |
items[].bookmark.title | string | yes | |
items[].bookmark.notes | string | yes | |
items[].bookmark.tags | array of string | yes | |
items[].bookmark.readLater | boolean | yes | |
items[].bookmark.isPublic | boolean | yes | |
items[].bookmark.archiveStatus | one of pending, ready, partial, failed | yes | |
items[].bookmark.archiveError | string | yes | |
items[].bookmark.linkStatus | one of unknown, alive, redirected, dead | yes | |
items[].bookmark.excerpt | string | yes | |
items[].bookmark.createdAt | string | yes | An ISO 8601 timestamp in UTC. |
items[].bookmark.updatedAt | string | yes | An ISO 8601 timestamp in UTC. |
items[].snippet | string | yes | |
nextOffset | integer or null | yes | The offset of the next page, or null after the last one. |