---
name: bookmarks-md
description: Fetch, search, and browse a user's X (Twitter) bookmarks from bookmarks.md. Use this skill when the user asks to retrieve their saved bookmarks, search through bookmarked tweets, or interact with their bookmarks.md account.
---

This skill enables AI agents to interact with a user's bookmarks stored on [bookmarks.md](https://bookmarks.md) — a service that syncs and stores X (Twitter) bookmarks.

## Prerequisites

The user must provide a **bookmarks.md API token**. Tokens are generated at `https://bookmarks.md/dashboard/settings` under the "Developer API" section. Tokens start with the prefix `bm_`.

If the user hasn't provided a token, ask them to:
1. Go to https://bookmarks.md/dashboard/settings
2. Scroll to the "Developer API" section
3. Create a new API token
4. Share the token with you (it starts with `bm_`)

## API Base URL

```
https://bookmarks.md/api/v1
```

## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer bm_YOUR_TOKEN_HERE
```

## Endpoints

### GET /api/v1/bookmarks

Fetch paginated bookmarks with optional search and filtering.

**Query Parameters:**

| Parameter | Type   | Default | Description                                      |
|-----------|--------|---------|--------------------------------------------------|
| `q`       | string | —       | Search text, author name, or @username           |
| `author`  | string | —       | Filter by exact X username (without @)           |
| `cursor`  | string | —       | Pagination cursor from previous response         |
| `limit`   | number | 50      | Results per page (1–100)                         |

**Response:**

```json
{
  "bookmarks": [
    {
      "tweetId": "1234567890",
      "text": "The tweet content...",
      "tweetUrl": "https://x.com/username/status/1234567890",
      "authorName": "Display Name",
      "authorUsername": "username",
      "authorProfileImageUrl": "https://pbs.twimg.com/...",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "savedAt": "2025-01-16T08:00:00.000Z",
      "note": "AI-generated commentary on the tweet (may be null)"
    }
  ],
  "nextCursor": "1705392000000",
  "total": 142
}
```

- `total` is only included on the first page (when no cursor is provided).
- `nextCursor` is `null` when there are no more results.
- To fetch the next page, pass `cursor=<nextCursor>` in the next request.

## Common Workflows

### Fetch all bookmarks

Make repeated requests, passing the `nextCursor` from each response as the `cursor` for the next, until `nextCursor` is `null`.

```bash
# First page
curl -H "Authorization: Bearer $TOKEN" \
  "https://bookmarks.md/api/v1/bookmarks?limit=100"

# Next page (using nextCursor from previous response)
curl -H "Authorization: Bearer $TOKEN" \
  "https://bookmarks.md/api/v1/bookmarks?limit=100&cursor=1705392000000"
```

### Search bookmarks

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://bookmarks.md/api/v1/bookmarks?q=machine+learning"
```

### Filter by author

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://bookmarks.md/api/v1/bookmarks?author=elonmusk"
```

### Combine search + author filter

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://bookmarks.md/api/v1/bookmarks?q=AI&author=sama"
```

## Error Handling

| Status | Meaning                        | Action                       |
|--------|--------------------------------|------------------------------|
| 200    | Success                        | Parse response JSON          |
| 400    | Bad request (invalid cursor)   | Fix the cursor parameter     |
| 401    | Invalid or missing token       | Check/regenerate token       |

## Tips for AI Agents

1. **Pagination**: Always check for `nextCursor` and continue fetching if the user wants "all" bookmarks.
2. **Rate awareness**: The API reads from a database, not the X API directly, so there are no strict rate limits — but be reasonable.
3. **Search is substring-based**: The `q` parameter does case-insensitive substring matching on tweet text, author name, and author username.
4. **Timestamps**: `savedAt` is when the bookmark was synced to bookmarks.md. `createdAt` is when the original tweet was posted.
5. **Token safety**: Never log or display the full API token. If you need to reference it, show only the first 7 characters.