Links

Save, find, change and delete links. A link is yours alone: saving a page someone else saved makes your own link to it.

List your links, newest first

GET/api/v1/bookmarks

Query

cursorstring

The next_cursor from the previous page.
Up to 200 characters
limitinteger

How many links per page.
1 to 100 · Default 30
collectionarray of string (uuid) or string

Collection ids; unsorted matches links in no collection. A link matches if it’s in any of them. Up to 20: comma-separated, repeated, or with brackets (name[]=).
1 to 20 items
tagarray of string (uuid)

Tag ids. A link matches if it has any of them. Up to 20: comma-separated, repeated, or with brackets (name[]=).
1 to 20 items
sourcearray of string (uuid)

Source ids. A link matches if any of them saved it. Up to 20: comma-separated, repeated, or with brackets (name[]=).
1 to 20 items
visibilitystring

Only public or only private links.
One of public, private
statusstring

dead: only links that no longer work.
Always dead
copystring

saved: only links with a saved copy of the page. full: only those whose copy keeps the whole page. none: only links without a copy.
One of saved, full, none
domainarray of string

Sites, like example.com. A link matches if it’s on any of them or their subdomains (example.com covers blog.example.com); www. is ignored. Up to 20: comma-separated, repeated, or with brackets (name[]=).
1 to 20 items
saved_afterstring (date) or string (date-time)

Only links saved at or after this: a day (2024-01-31, from midnight UTC) or a time.
saved_beforestring (date) or string (date-time)

Only links saved before this: a day (2024-01-31, before midnight UTC) or a time.
qstring

Search titles, descriptions, notes and saved pages. Title matches come first, then other details, then saved pages; newest first within each.
Up to 200 characters

Returns

200A page of Bookmark objects, with next_cursor
400 401 404 429Errors

curl https://trovemarks.com/api/v1/bookmarks \
  -H "Authorization: Bearer tm_…"

Save a link

POST/api/v1/bookmarks

Returns straight away; the title, description and icon are fetched in the background. Saving a link that is already saved returns 200 instead of 201 and only adds any new collections and tags: title, note and private are ignored, so change those with PATCH /bookmarks/{id}.

Body

urlstringrequired

The link. A bare domain like example.com is fine; it’s normalised before saving.
Up to 2048 characters
titlestring

Your own title. Leave it out to use the page’s title, which is fetched after the save returns; until then the link shows its URL.
Up to 300 characters
notestring

Up to 2000 characters
privateboolean

Leave it out to use the source’s default, then your account’s.
collection_idsarray of string (uuid)

Collections to add the link to. With neither this nor collection_names, a new link goes in the source’s default collection, if it has one.
Up to 20 items
collection_namesarray of string

Collections by title, matched ignoring case; missing ones are created, private. Added to collection_ids. On the free plan, names past the collection limit become tags instead and are listed in collection_names_as_tags.
Up to 20 items
tagsarray of string

Tag names, matched ignoring case; missing ones are created. A leading # is dropped and commas aren’t allowed. When a tag already exists its spelling is kept. The source’s automatic tags are added too.
Up to 20 items

Returns

200Already saved · object
201Saved · object
400 401 404 429Errors

curl -X POST https://trovemarks.com/api/v1/bookmarks \
  -H "Authorization: Bearer tm_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Change, file or delete many links at once

POST/api/v1/bookmarks/bulk

Send either ids (up to 500) or a filter (the list filters and search, up to 10,000 matching links) and one action. Visibility, tags and collections change straight away; copies are queued. Filing into a collection keeps each link’s visibility but takes a fuller copy if the collection keeps one.

Body

idsarray of string (uuid)

Links picked one by one.
1 to 500 items
filterobject

Every link matching these list filters and search, up to 10,000.
- collectionstring or array of string
  
  Collection ids; unsorted matches links in no collection. A link matches if it’s in any of them. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- tagstring or array of string
  
  Tag ids. A link matches if it has any of them. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- sourcestring or array of string
  
  Source ids. A link matches if any of them saved it. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- visibilitystring
  
  Only public or only private links.
  One of public, private
- statusstring
  
  dead: only links that no longer work.
  Always dead
- copystring
  
  saved: only links with a saved copy of the page. full: only those whose copy keeps the whole page. none: only links without a copy.
  One of saved, full, none
- domainstring or array of string
  
  Sites, like example.com. A link matches if it’s on any of them or their subdomains (example.com covers blog.example.com); www. is ignored. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- saved_afterstring (date) or string (date-time)
  
  Only links saved at or after this: a day (2024-01-31, from midnight UTC) or a time.
- saved_beforestring (date) or string (date-time)
  
  Only links saved before this: a day (2024-01-31, before midnight UTC) or a time.
- qstring
  
  Search titles, descriptions, notes and saved pages. Title matches come first, then other details, then saved pages; newest first within each.
  Up to 200 characters
actionobjectrequired
When type is visibility
- typestringrequired
  
  Always visibility
- privatebooleanrequired
When type is copy
- typestringrequired
  
  Always copy
- modestringrequired
  
  readable or full keeps a copy where a link has a less complete one; off removes copies.
  One of off, readable, full
When type is tags
- typestringrequired
  
  Always tags
- addarray of string
  
  Tag names; new ones are created.
  Up to 20 items
- removearray of string (uuid)
  
  Tag ids.
  Up to 100 items
When type is collections
- typestringrequired
  
  Always collections
- addarray of string (uuid)
  
  Up to 20 items
- removearray of string (uuid)
  
  Up to 100 items
When type is delete
- typestringrequired
  
  Always delete

Returns

200What changed · BulkResult
400 401 404 429Errors

curl -X POST https://trovemarks.com/api/v1/bookmarks/bulk \
  -H "Authorization: Bearer tm_…" \
  -H "Content-Type: application/json" \
  -d '{"action":{"type":"visibility","private":false}}'

Describe a selection of links

POST/api/v1/bookmarks/bulk/summary

How many links ids or filter covers, and their visibility, copies, collections and tags.

Body

idsarray of string (uuid)

Links picked one by one.
1 to 500 items
filterobject

Every link matching these list filters and search, up to 10,000.
- collectionstring or array of string
  
  Collection ids; unsorted matches links in no collection. A link matches if it’s in any of them. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- tagstring or array of string
  
  Tag ids. A link matches if it has any of them. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- sourcestring or array of string
  
  Source ids. A link matches if any of them saved it. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- visibilitystring
  
  Only public or only private links.
  One of public, private
- statusstring
  
  dead: only links that no longer work.
  Always dead
- copystring
  
  saved: only links with a saved copy of the page. full: only those whose copy keeps the whole page. none: only links without a copy.
  One of saved, full, none
- domainstring or array of string
  
  Sites, like example.com. A link matches if it’s on any of them or their subdomains (example.com covers blog.example.com); www. is ignored. Up to 20: comma-separated, repeated, or with brackets (name[]=).
- saved_afterstring (date) or string (date-time)
  
  Only links saved at or after this: a day (2024-01-31, from midnight UTC) or a time.
- saved_beforestring (date) or string (date-time)
  
  Only links saved before this: a day (2024-01-31, before midnight UTC) or a time.
- qstring
  
  Search titles, descriptions, notes and saved pages. Title matches come first, then other details, then saved pages; newest first within each.
  Up to 200 characters

Returns

200The selection · BulkSummary
400 401 404 429Errors

curl -X POST https://trovemarks.com/api/v1/bookmarks/bulk/summary \
  -H "Authorization: Bearer tm_…" \
  -H "Content-Type: application/json" \
  -d '{"ids":["0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40"],"filter":{"collection":"text","tag":"text"}}'

Find your saved link for a URL

GET/api/v1/bookmarks/lookup

Query

urlstringrequired

Returns

200The link · Bookmark
400 401 404 429Errors

curl https://trovemarks.com/api/v1/bookmarks/lookup?url=https%3A%2F%2Fexample.com%2Farticle \
  -H "Authorization: Bearer tm_…"

Get a link

GET/api/v1/bookmarks/{id}

Path

idstring (uuid)required

Returns

200The link · Bookmark
400 401 404 429Errors

curl https://trovemarks.com/api/v1/bookmarks/0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40 \
  -H "Authorization: Bearer tm_…"

Change a link

PATCH/api/v1/bookmarks/{id}

collection_ids and tags replace what is there.

Path

idstring (uuid)required

Body

urlstring

Moves the bookmark to another link, e.g. to drop extra query parameters. Fails with 409 if that link is already in your library.
Up to 2048 characters
titlestring or null

Up to 300 characters
notestring or null

Up to 2000 characters
privateboolean
collection_idsarray of string (uuid)

Up to 20 items
tagsarray of string

Up to 20 items
comments_disabledboolean

Returns

200The link · Bookmark
400 401 404 429Errors

curl -X PATCH https://trovemarks.com/api/v1/bookmarks/0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40 \
  -H "Authorization: Bearer tm_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","title":"A good read"}'

Move a link to the trash

DELETE/api/v1/bookmarks/{id}

It leaves every list and collection at once. Restore it from the trash in the web app within 30 days; after that it’s gone for good.

Path

idstring (uuid)required

Returns

204Deleted
400 401 404 429Errors

curl -X DELETE https://trovemarks.com/api/v1/bookmarks/0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40 \
  -H "Authorization: Bearer tm_…"