docs/api

api reference

The keep API lets you save URLs, list your bookmarks, retrieve extracted markdown, and manage your account. All responses are JSON.

base url

https://keepmarkdown.com/api

authentication

All requests require a Bearer token in the Authorization header. You can create a personal API key from your dashboard. Personal keys have full read/write access. Extension keys are restricted to sync only.

curl https://keepmarkdown.com/api/me \
  -H "Authorization: Bearer $KEEP_API_KEY"

rate limits

Free accounts have a lifetime cap of 50 saved links. Paid plans (Plus, Pro) reset monthly. When your limit is reached, write requests return 429 with error: "quota_reached". Read requests are never limited.

errors

Errors return a JSON object with an error field and an appropriate HTTP status code.

// 401 — missing or invalid token
{ "error": "unauthorized" }

// 429 — plan limit reached
{ "error": "quota_reached", "plan": "free", "linkLimit": 50, "linkCount": 50 }

// 404 — item not found
{ "error": "not_found" }

GET /api/me

Returns your plan, limits, and usage counts.

curl https://keepmarkdown.com/api/me \
  -H "Authorization: Bearer $KEEP_API_KEY"

{
  "plan": "plus",
  "linkLimit": 500,
  "linkCount": 42,
  "linkCountMonth": 12,
  "linkCountLifetime": 87
}

GET /api/stats

Usage statistics for a date range.

since — start of range (timestamp, ISO date, or relative like 7d, 24h). until — end of range (optional).

curl "https://keepmarkdown.com/api/stats?since=7d" \
  -H "Authorization: Bearer $KEEP_API_KEY"

{
  "total": 12,
  "byStatus": { "stashed": 10, "flagged": 2 },
  "range": { "since": "...", "until": "...", "count": 12 }
}

GET /api/items

List your saved items. Archived items are excluded by default.

since / until — filter by time. status — comma-separated filter (e.g. stashed,flagged). q — search title, URL, notes, tags (hybrid retrieval). content=1 — include full markdown. limit — 1–1000, default 200. offset — pagination offset.

curl "https://keepmarkdown.com/api/items?limit=10&content=1" \
  -H "Authorization: Bearer $KEEP_API_KEY"

{
  "items": [
    {
      "id": "a1b2c3",
      "url": "https://example.com/article",
      "title": "Example Article",
      "status": "stashed",
      "createdAt": 1709251200,
      "contentAvailable": true,
      "contentMarkdown": "# Example Article\n\nThe full extracted markdown..."
    }
  ],
  "limit": 10,
  "offset": 0,
  "count": 1
}

GET /api/items/:id

Get a single item by ID. Add ?content=1 to include the extracted markdown.

curl https://keepmarkdown.com/api/items/a1b2c3 \
  -H "Authorization: Bearer $KEEP_API_KEY"

GET /api/items/:id/content

Returns the extracted markdown as plain text. Response headers include x-content-size and x-content-truncated.

curl https://keepmarkdown.com/api/items/a1b2c3/content \
  -H "Authorization: Bearer $KEEP_API_KEY"

POST /api/ingest

Save a URL. The page is fetched and its content extracted as markdown in the background. Duplicate URLs are deduplicated automatically.

curl -X POST https://keepmarkdown.com/api/ingest \
  -H "Authorization: Bearer $KEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/article" }'

{
  "ok": true,
  "id": "a1b2c3",
  "url": "https://example.com/article",
  "extracted": true
}

POST /api/items/archive

Archive items by ID. Archived items are hidden from the default list.

curl -X POST https://keepmarkdown.com/api/items/archive \
  -H "Authorization: Bearer $KEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["a1b2c3"] }'

{ "archived": 1 }

POST /api/items/delete

Permanently delete items by ID.

curl -X POST https://keepmarkdown.com/api/items/delete \
  -H "Authorization: Bearer $KEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["a1b2c3"] }'

{ "deleted": 1 }

GET /api/feed

Returns unprocessed items with their full extracted content. Designed for AI agents that consume your bookmarks as context. Supports the same since, until, q, limit, and offset params as /api/items.

curl "https://keepmarkdown.com/api/feed?limit=5" \
  -H "Authorization: Bearer $KEEP_API_KEY"

POST /api/items/mark-processed

Mark items as processed so they no longer appear in the feed.

curl -X POST https://keepmarkdown.com/api/items/mark-processed \
  -H "Authorization: Bearer $KEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["a1b2c3", "d4e5f6"] }'

{ "processed": 2 }

POST /api/items/sync

Bulk sync items from the Chrome extension. Accepts up to 1000 items per request. Existing URLs are deduplicated.

curl -X POST https://keepmarkdown.com/api/items/sync \
  -H "Authorization: Bearer $KEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "url": "https://example.com", "title": "Example" }] }'

{
  "added": 1,
  "upserted": 0,
  "skipped": 0,
  "limitReached": false
}

openapi.json

← cli

mobile →