LinkArena API documentation
Reference for the LinkArena REST API: get a bearer token, then save, update, delete, and sync bookmarks and groups.
The LinkArena API is a JSON REST API served from https://linkarena.app. It is the same API the Chrome extension and the Android app use, so a script or an AI agent can do with a library what those apps do. Every bookmark endpoint acts on one user's private library and needs that user's API token.
When to use the LinkArena API
- Save a URL into a user's LinkArena library from a script, an agent, or another app, optionally into a named group.
- Read a user's bookmarks and groups to search, summarize, deduplicate, or back them up.
- Reorganize a library: move bookmarks between groups, rename or reorder groups, or delete bookmarks.
- Keep another tool up to date with a library by listening to the realtime event stream.
The API is not a public link directory: there is no anonymous search across users. AI apps such as Claude and ChatGPT should use the MCP server (see Use LinkArena from AI apps below); scripts call the REST endpoints directly. There is no SDK or CLI.
Use LinkArena from AI apps (MCP)
LinkArena runs a remote Model Context Protocol server at https://linkarena.app/api/mcp, so Claude, ChatGPT and other MCP clients can search, save and organize a user's bookmarks. It is included in LinkArena Pro.
- Claude: Settings, Connectors, Add custom connector. Paste the server URL, then sign in to LinkArena and click Allow.
- ChatGPT and other apps: add a custom connector or remote MCP server with the URL and choose OAuth.
- Claude Code: claude mcp add --transport http linkarena https://linkarena.app/api/mcp, then run /mcp to sign in.
- Clients without OAuth support can send an API token in the Authorization header instead.
Tools: search, fetch, save_bookmark, update_bookmark, move_bookmarks, set_bookmark_state, tag_bookmarks, list_tags, delete_bookmark, list_groups, create_group and update_group. Saves and content edits count against the plan's monthly quota exactly like the REST API; tags and favorite, read later and archive changes don't.
Sign-in uses OAuth 2.1: authorization code with PKCE (S256), Dynamic Client Registration, and refresh tokens. Clients discover it from the WWW-Authenticate header of a 401 response. Users see and disconnect connected apps in Settings, AI apps.
Get an API token
Tokens are self-serve and available on the free plan. Create a free account (no card required), verify your email, then use either method:
- In the browser: open the dashboard, open the profile menu, and choose Generate API Token. Copy the token right away; it is shown only once.
- Programmatically: send your email and password to POST /api/mobile/auth/login. The response contains a token, the user, and the plan entitlements.
curl -X POST https://linkarena.app/api/mobile/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"your-password","tokenName":"my-script"}'Tokens expire after 90 days. Revoke one from the same dialog, or call POST /api/mobile/auth/logout with the token. There is no separate sandbox environment; use a second free account for testing.
Authentication
Send the token in the Authorization header on every request. Requests without a valid token get HTTP 401 with a JSON error body.
curl https://linkarena.app/api/sync?limit=50 \
-H "Authorization: Bearer $LINKARENA_TOKEN"Endpoints
- GET /api/sync: bookmarks (newest first) and groups. Optional query: limit, cursor (the nextCursor from the previous page), mode=initial. Returns { bookmarks, groups, hasMore, nextCursor }.
- POST /api/bookmarks: save a bookmark. Body: { url, title?, description?, groupId?, fetchMetadata? }. Set fetchMetadata to true to have the server fill in the title, description, and icon. Saving a URL that already exists in the same group updates it.
- PUT /api/bookmarks: update a bookmark found by its URL. Body: { url, title?, description?, groupId? }.
- DELETE /api/bookmarks: delete a bookmark by URL. Body: { url }. Returns 204.
- DELETE /api/bookmarks/{id}: delete a bookmark by id. Returns 204.
- POST /api/bookmarks/{id}: fetch the page again and refresh the bookmark's title, description, and icon.
- PUT /api/bookmarks/{id}/category: move a bookmark to a group. Body: { groupId } (null removes it from its group).
- GET /api/groups: list groups with bookmark counts.
- POST /api/groups: create a group. Body: { name, color? }.
- PATCH /api/groups/{id}: rename, recolour, or reorder a group. Body: { name?, color?, order? }.
- DELETE /api/groups/{id}: delete a group. Returns 204.
- GET /api/export: the whole library as a JSON array.
- GET /api/realtime/bookmarks: a Server-Sent Events stream of bookmark.* and group.* change events.
- GET /api/plans: public, no token needed. Lists each plan with its features and monthly bookmark quota.
Limits and errors
- New bookmarks count against the plan's monthly quota; reads, updates, and deletes do not. GET /api/plans shows the current quota for each plan (null means no cap).
- Writes return 429 once the monthly quota is used up, and 403 when the request needs a feature the user's plan does not include.
- The login endpoint allows 10 attempts per 15 minutes per IP address and returns 429 with a Retry-After header after that.
- Errors are JSON objects of the form { "error": "message" }.
Machine-readable resources
- OpenAPI 3.1 specification (JSON)
- llms.txt (summary and when-to-use guidance for AI agents)
- OAuth authorization server metadata (RFC 8414)
- OAuth protected resource metadata (RFC 9728)
- MCP protected resource metadata (RFC 9728, for the MCP server)
Questions about the API? Email [email protected].