The tinykoi REST API in ten minutes with curl
· Developers · 4 min read
The tinykoi bookmark manager API is a plain REST API under /api/v1. You create a key in Settings, send it as a bearer token, and read or change your library with ordinary JSON requests. This guide gets you from nothing to a saved, tagged and searchable bookmark using only curl.
If you want the reasoning behind having an API at all, why developers need a bookmark manager with an API covers it. This post is the practical half. The full reference, generated from the same code that serves the requests, lives at /api/v1.
Create an API key
Open Settings and find the API keys section. Give the key a name (up to 32 characters) and choose whether it can write. A read key can call every GET route. A read and write key can call all of them.
tinykoi shows the full key once, then stores only a hash, so copy it straight away. Every key starts with tinykoi_, which makes a leaked one easy to spot and scan for. The Free plan holds 1 key, and Pro holds 10.
Put it in an environment variable so it stays out of your shell history:
export TINYKOI_KEY="tinykoi_..."
export API="https://tinykoi.com/api/v1"
Authenticate with a bearer token
Every request carries an Authorization: Bearer header. The /me route is the easiest way to check it works:
curl -s "$API/me" -H "Authorization: Bearer $TINYKOI_KEY"
You get back your user, your plan, the entitlements for that plan and this month's usage (period, uploadBytes, captures). If the header is missing you get a 401 telling you to send an API key as Authorization: Bearer <key>. A key that does not exist gets a 401 saying Invalid API key.
Errors share one JSON shape with defined, code, status and message, plus a data object for some codes.
List and look up bookmarks
Listing needs a scope. The simple scopes are all, unsorted, favorites and trash:
curl -s "$API/bookmarks?scope=all&limit=5&sort=created_desc" \
-H "Authorization: Bearer $TINYKOI_KEY"
The response is { "items": [...], "nextCursor": "..." }. Pass nextCursor back as cursor to get the next page. limit runs from 1 to 100 and defaults to 50. sort takes manual, created_desc, created_asc, title or domain.
Each item carries id, url, domain, title, excerpt, note, favorite, tags, collectionId, type, status and archiveStatus, plus timestamps and a link object for link health.
To fetch one bookmark, use its id: GET /bookmarks/{id}. To check whether a URL is already saved, use the lookup route:
curl -s -G "$API/bookmarks/lookup" \
--data-urlencode "url=https://example.com/article" \
-H "Authorization: Bearer $TINYKOI_KEY"
It returns the bookmark, or null when you have not saved that URL.
Save a bookmark
Saving is a POST to /bookmarks with a JSON body. Only url is required. You can also send title, excerpt, note, tags and a collectionId:
curl -s -X POST "$API/bookmarks" \
-H "Authorization: Bearer $TINYKOI_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/article","tags":["reading"],"note":"for Friday"}'
The reply is { "bookmark": {...}, "created": true }. If you already had that page, created is false and you get the existing bookmark back, so repeated saves never make duplicates.
The title, excerpt and cover are fetched in the background. A new bookmark starts with status set to pending and moves to ready (or failed). Fetch it again by id after a few seconds to see the finished version.
New saves count against your saves-an-hour limit: 120 on Free and 600 on Pro. Go over it and the API answers 429 with RATE_LIMITED and data.retryAfterSeconds. A read key trying this gets a 403 saying the key lacks write access.
Search your library
Search is GET /search with a q of up to 200 characters:
curl -s -G "$API/search" --data-urlencode "q=postgres index" \
-H "Authorization: Bearer $TINYKOI_KEY"
The response has the same page shape as the list, and each item has one extra field, snippet. When your words matched the saved page text, snippet holds an excerpt with each match wrapped in two private-use characters, U+E000 before and U+E001 after. Split on those to highlight matches yourself. When the match was in the title, tags or notes, snippet is null.
On Pro with AI switched on in Settings, search also returns up to 30 bookmarks that match by meaning, in the same list.
Tag and organise
Add or remove tags on many bookmarks at once, up to 100 ids per call:
curl -s -X POST "$API/bookmarks/tag" \
-H "Authorization: Bearer $TINYKOI_KEY" \
-H "Content-Type: application/json" \
-d '{"ids":["<bookmark-id>"],"add":["research"],"remove":["reading"]}'
You get { "updated": 1 }. The other write routes follow the same pattern: PATCH /bookmarks/{id} to edit a title, note or favourite, POST /bookmarks/move to put bookmarks in a collection, and POST /bookmarks/trash and /bookmarks/restore for the trash. Collections, tags and highlights each have their own routes. Browse them all in the reference.
Bookmark manager API limits
Requests are counted per account across all your keys, per minute: 20 on Free and 120 on Pro. Extra keys add no capacity. Every response carries ratelimit-limit, ratelimit-remaining and ratelimit-reset, and a 429 adds retry-after.
Uploads, imports, billing and key management are not part of the API. They stay in the app. See pricing for the full plan limits.
Reading failures
Check the HTTP status first, then code in the body. A 401 means a missing or invalid key, a 403 means your key lacks the access the route needs, a 404 means no such bookmark or route, and a 429 means you hit a rate limit. A 422 means the request was malformed, with the reason in data.reason. Print the whole body while you are developing. It usually says exactly what is wrong.
Try it
Make a free account, create a key, and run the /me call above. It takes about two minutes. Sign up free, no card needed.
tinykoi