keep-markdown

Search and retrieve saved web content as clean Markdown from the keep.md API. Users save web pages via the keep.md browser extension or CLI, and this skill lets you search, list, and read that content.

Authentication

You need an API key to use keep.md. The user must provide one or have it set in their environment.

1. Sign up at https://keep.md
2. Go to https://keep.md/dashboard
3. Create a personal API token
4. Save the key:

npx keep-markdown key <your-token>

This persists the key to ~/.config/keep-markdown/config.json. Alternatively set the KEEP_API_KEY environment variable.

All CLI commands and API requests require this token. The API accepts it via Authorization: Bearer <token> header.

CLI Commands

Install nothing - use npx. Every command below works immediately.

Check account info

npx keep-markdown me

Returns your account ID, plan, link limit, and current link count.

List saved items

npx keep-markdown list

List items from the last 7 days

npx keep-markdown list --since 7d

List items with their Markdown content included

npx keep-markdown list --since 24h --content

Search items by keyword

npx keep-markdown search "react hooks"

Searches across titles, URLs, notes, and tags. This is equivalent to list --query "react hooks".

List with query flag

npx keep-markdown list --query "typescript" --limit 10

Get item metadata by ID

npx keep-markdown get <id>

Returns JSON with the item's URL, title, tags, status, content availability, and timestamps.

Get item content as Markdown

npx keep-markdown content <id>

Returns the extracted Markdown content of the saved page. This is the primary way to read saved web content.

Get usage statistics

npx keep-markdown stats

Get stats for a date range

npx keep-markdown stats --since 30d

Output raw JSON

Any command supports --json for machine-readable output:

npx keep-markdown list --since 7d --json

HTTP API Reference

Base URL: https://keep.md

All endpoints require Authorization: Bearer <token> header.

GET /api/me

Returns account info.

curl -H "Authorization: Bearer $KEEP_API_KEY" https://keep.md/api/me

Response:

{
  "accountId": "uuid",
  "authType": "api",
  "plan": "free",
  "linkLimit": 50,
  "linkCount": 12
}

GET /api/items

List saved items. Returns newest first.

Query parameters:

• since — timestamp (ms) or relative like 7d, 24h
• until — timestamp (ms) or relative
• status — comma-separated status filter (e.g. stashed,active)
• q — search query (searches title, URL, notes, tags)
• limit — max items to return (default 200, max 1000)
• offset — pagination offset
• content — set to 1 to include Markdown content in response

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

Response:

{
  "items": [
    {
      "id": "sha256-hash",
      "url": "https://example.com/article",
      "title": "Example Article",
      "status": "stashed",
      "createdAt": 1706745600000,
      "contentAvailable": true,
      "contentMarkdown": "# Article Title\n\nArticle content..."
    }
  ],
  "limit": 10,
  "offset": 0,
  "count": 1
}

GET /api/items/:id

Get a single item's metadata.

curl -H "Authorization: Bearer $KEEP_API_KEY" https://keep.md/api/items/<id>

Add ?content=1 to include Markdown content in the response.

GET /api/items/:id/content

Get the extracted Markdown content for an item. Returns text/markdown.

curl -H "Authorization: Bearer $KEEP_API_KEY" https://keep.md/api/items/<id>/content

Response headers include:

• x-content-size — content size in bytes
• x-content-truncated — 1 if content was truncated, 0 otherwise

Returns 404 if no content has been extracted for this item.

GET /api/stats

Get usage statistics.

curl -H "Authorization: Bearer $KEEP_API_KEY" "https://keep.md/api/stats?since=30d"

Response:

{
  "total": 42,
  "byStatus": { "stashed": 30, "active": 12 },
  "content": { "errors": 2, "missing": 5 },
  "range": { "since": 1704067200000, "until": null, "count": 15 }
}

Item Fields

Each item has these fields:

• id — SHA-256 hash of the URL (unique identifier)
• url — the saved page URL
• title — page title
• status — e.g. stashed
• tags — array of tag strings
• notes — user notes
• createdAt — timestamp (ms) when first saved
• lastSeenAt — timestamp (ms) when last seen
• contentAvailable — true if Markdown content has been extracted
• contentSize — content size in bytes
• contentTruncated — true if content exceeded the size limit (~500KB)
• contentExtractError — error message if extraction failed

Common Workflows

Find and read a saved article

First search for it:

npx keep-markdown search "article title"

Then read the content using the item ID from the results:

npx keep-markdown content <id>

List recent saves with content

npx keep-markdown list --since 7d --content --json

Check if content is available before reading

npx keep-markdown get <id>

Look at the contentAvailable field. If false, content hasn't been extracted yet.

Check your usage

npx keep-markdown me

Constraints

• Content is capped at ~500KB per item — check contentTruncated field
• Free plan: 50 saved links, Plus: 1,000, Pro: 3,000
• List endpoint returns max 1,000 items per request (default 200)
• Use offset for pagination through larger collections

OpenAPI Specification

Full API spec available at: https://keep.md/openapi.json