Collections

List your collections, by title

GET/api/v1/collections

Query

• cursorstring
  The next_cursor from the previous page.
  Up to 100 characters
• limitinteger
  How many per page, up to 500.
  1 to 500 · Default 100

Returns

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

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

Create a collection

POST/api/v1/collections

Titles are unique ignoring case: a clash is a 409 with title_taken. Without a slug one is made from the title; a slug you choose that’s in use is a 409 with slug_taken.

Body

• titlestringrequired
  Up to 80 characters
• descriptionstring
  Up to 300 characters
• privateboolean
  Default true
• slugstring
  Up to 60 characters
• default_privateboolean or null
  Visibility for links saved into this collection. Beats the source’s default; null uses it.
• archive_modestring or null
  Copy to keep of links saved into this collection. Beats the source’s; null uses it.
  One of off, readable, full

Returns

• 201Created · Collection
• 400 401 404 409 429Errors

curl -X POST https://trovemarks.com/api/v1/collections \
  -H "Authorization: Bearer tm_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"A good read"}'

Get a collection

GET/api/v1/collections/{id}

Path

• idstring (uuid)required

Returns

• 200The collection · Collection
• 400 401 404 429Errors

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

Change a collection

PATCH/api/v1/collections/{id}

A title or slug another of your collections has is a 409 with title_taken or slug_taken.

Path

• idstring (uuid)required

Body

• titlestring
  Up to 80 characters
• descriptionstring or null
  Up to 300 characters
• privateboolean
• slugstring
  Up to 60 characters
• default_privateboolean or null
  Visibility for links saved into this collection. Beats the source’s default; null uses it.
• archive_modestring or null
  Copy to keep of links saved into this collection. Beats the source’s; null uses it.
  One of off, readable, full

Returns

• 200The collection · Collection
• 400 401 404 409 429Errors

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

Delete a collection (its links stay in your library)

DELETE/api/v1/collections/{id}

Path

• idstring (uuid)required

Returns

• 204Deleted
• 400 401 404 429Errors

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

Add links to a collection

POST/api/v1/collections/{id}/items

Path

• idstring (uuid)required

Body

• bookmark_idsarray of string (uuid)required
  1 to 200 items

Returns

• 204Added
• 400 401 404 429Errors

curl -X POST https://trovemarks.com/api/v1/collections/0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40/items \
  -H "Authorization: Bearer tm_…" \
  -H "Content-Type: application/json" \
  -d '{"bookmark_ids":["0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40"]}'

Remove links from a collection

DELETE/api/v1/collections/{id}/items

Path

• idstring (uuid)required

Body

• bookmark_idsarray of string (uuid)required
  1 to 200 items

Returns

• 204Removed
• 400 401 404 429Errors

curl -X DELETE https://trovemarks.com/api/v1/collections/0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40/items \
  -H "Authorization: Bearer tm_…" \
  -H "Content-Type: application/json" \
  -d '{"bookmark_ids":["0b7e4c1a-5d2f-4e8a-9c3b-6a1f2e8d7c40"]}'

Apply a collection’s defaults to the links already in it

POST/api/v1/collections/{id}/apply-defaults

Sets each link’s visibility to the collection’s default_private, if it has one, and queues a copy for links with a less complete one than its archive_mode. Changing the defaults alone only affects links saved afterwards.

Path

• idstring (uuid)required

Returns

• 200What changed · AppliedDefaults
• 400 401 404 429Errors

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

Who follows one of your collections, newest first

GET/api/v1/collections/{id}/followers

Only the collection’s owner can see this.

Path

• idstring (uuid)required

Query

• cursorstring
  The next_cursor from the previous page.
  Up to 100 characters
• limitinteger
  How many per page, up to 100.
  1 to 100 · Default 50

Returns

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

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