mymarks beta
We're still building — things may change, but your bookmarks are safe and nothing will be deleted.

API Reference

Manage your bookmarks and tags programmatically. All endpoints return JSON.

Authentication

Every request must include your API key. Generate one in Settings → API key.

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Or via the X-Api-Key header:

X-Api-Key: YOUR_API_KEY

Base URL

All endpoints are relative to:

https://mymarks.net/api/v1

CORS is enabled for all origins, so the API can be called from browser extensions or other web apps.

Errors

All errors return a JSON body with an error key.

{ "error": "Invalid API key." }
Status Meaning
400Malformed JSON body
401Missing or invalid API key
404Bookmark not found (or belongs to another user)
422Validation error (missing required field)

Bookmarks

The bookmark object

{
  "id":          1,
  "url":         "https://example.com",
  "title":       "Example",
  "description": "An optional note.",
  "tags":        ["reading", "dev"],
  "is_private":  false,
  "is_archived": false,
  "is_starred":  false,
  "created_at":  "2026-03-25T10:00:00+00:00",
  "updated_at":  null
}
GET /api/v1/bookmarks

Returns a paginated list of your bookmarks.

Query parameters

Parameter Type Default Description
page integer 1 Page number.
per_page integer 30 Results per page (max 100).
q string Search query (title, URL, description, tags).
tag string Filter by exact tag name.
sort string date_desc One of: date_desc, date_asc, title_asc, title_desc.
visibility string Filter to public or private.
starred boolean false Return only starred bookmarks.
archived boolean false Return archived bookmarks instead of active ones.

Response 200

{
  "data": [ /* bookmark objects */ ],
  "meta": {
    "total":       42,
    "page":        1,
    "per_page":    30,
    "total_pages": 2
  }
}
POST /api/v1/bookmarks

Creates a new bookmark. Returns the created object with status 201.

Request body application/json

Parameter Type Required Description
url string required The URL to bookmark (max 2048 chars).
title string required Display title (max 255 chars).
description string optional Optional free-text note.
tags string[] optional Array of tag names. New tags are created automatically.
is_private boolean optional Defaults to your account default.
is_starred boolean optional Defaults to false. 
POST /api/v1/bookmarks HTTP/1.1
Content-Type: application/json

{
  "url":        "https://example.com",
  "title":      "Example",
  "tags":       ["reading"],
  "is_private": false
}
GET /api/v1/bookmarks/{id}

Returns a single bookmark by ID.

Response 200

{ "data": { /* bookmark object */ } }
PUT /api/v1/bookmarks/{id}

Updates a bookmark. Only fields present in the body are changed. PATCH is also accepted.

Request body application/json

Parameter Type Required Description
url string optional New URL.
title string optional New title.
description string optional Pass null to clear.
tags string[] optional Replaces the entire tag list.
is_private boolean optional
is_starred boolean optional
is_archived boolean optional

Response 200

{ "data": { /* updated bookmark object */ } }
DELETE /api/v1/bookmarks/{id}

Deletes a bookmark permanently. Returns 204 No Content.

GET /api/v1/bookmarks/check

Checks whether a URL is already in your collection.

Query parameters

Parameter Type Required Description
url string required The URL to look up (URL-encoded).

Response 200

// Not saved
{ "exists": false }

// Already saved
{ "exists": true, "bookmark": { /* bookmark object */ } }

Tags

GET /api/v1/tags

Returns all your tag names, sorted alphabetically. Pass q to search.

Query parameters

Parameter Type Required Description
q string optional Partial name to search (max 20 results).

Response 200

{ "data": ["dev", "reading", "tools"] }

Full example

Save a bookmark and add it to a tag, using curl:

curl -X POST https://mymarks.net/api/v1/bookmarks 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"url":"https://example.com","title":"Example","tags":["reading"]}'