Skip to main content
mymarks

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"]}'