Use this skill when you need to interact with the hosted Bookmark Agent API at `https://bookmark-agent.com`.

## Base URL

- Hosted app: `https://bookmark-agent.com`
- Hosted API base: `https://bookmark-agent.com/api`
- Do not assume `/api/v1`; this API is mounted directly under `/api`
- If the user runs a self-hosted instance, ask for the base URL and replace `https://bookmark-agent.com`

## Auth

Prefer API keys for normal API usage.

Use email/password only for:
- signing in to create the first API key
- rotating a lost or compromised API key

Do not ask the user for email/password if they already have an API key.

## Auth Flow

### 1. Sign in to get a session cookie

Use this only for API key bootstrap or recovery:

```bash
curl -s -c /tmp/bookmark-agent-cookies.txt \
  -X POST "https://bookmark-agent.com/api/auth/sign-in/email" \
  -H "Content-Type: application/json" \
  -d '{"email":"<EMAIL>","password":"<PASSWORD>"}'
```

### 2. Bootstrap the first API key

```bash
curl -s -b /tmp/bookmark-agent-cookies.txt \
  -X POST "https://bookmark-agent.com/api/account/api-key/bootstrap"
```

The response returns:
- `apiKey`: metadata
- `created`: whether a new key was created
- `token`: plaintext API key, shown only when a new key is created

### 3. Use the API key for normal requests

```bash
curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "https://bookmark-agent.com/api/bookmarks"
```

### 4. Rotate a lost or compromised API key

Rotation requires a signed-in session, not the old API key:

```bash
curl -s -b /tmp/bookmark-agent-cookies.txt \
  -X POST "https://bookmark-agent.com/api/account/api-key/roll"
```

## Session-Only Endpoints

These require session auth and should not be called with only a bearer API key:

### GET /api/account/api-key

Return metadata for the current active API key.

### POST /api/account/api-key/bootstrap

Create the first API key for the signed-in user. Returns the plaintext token only on first creation.

### POST /api/account/api-key/roll

Revoke the current API key and return a new one.

## Bearer-Friendly Endpoints

These accept `Authorization: Bearer <API_KEY>` or a session cookie.

### POST /api/bookmarks

Create a bookmark.

Required:
- `url`

Optional:
- `title`
- `notes`
- `tags` as `string[]`
- `folderPath`
- `savedAt` as ISO datetime

### GET /api/bookmarks

List bookmarks.

Query params:
- `archived`
- `importId`
- `limit` from `1` to `200`, default `50`

### GET /api/bookmarks/:id

Return one bookmark by ID.

### PATCH /api/bookmarks/:id

Update a bookmark.

Allowed fields:
- `notes`
- `tags`
- `archived`

### DELETE /api/bookmarks/:id

Delete a bookmark.

### POST /api/bookmarks/:id/refetch

Re-fetch bookmark content asynchronously.

### GET /api/imports

List all imports for the current user.

### GET /api/imports/:id

Return one import status.

## Public Endpoint

### GET /api/health

Health check. No auth required.

## Operating Rules

- Prefer bearer auth for bookmark operations.
- Use session auth only for API key bootstrap and rotation.
- If a bearer-auth request returns `401`, ask whether the user wants to rotate the API key or provide a valid one.
- Do not silently fall back to email/password for normal business requests.
- IDs are string IDs.
- Bookmark content fetching is asynchronous after create or refetch.
- `folderPath` uses `/` separators such as `"dev/tools"`.
- Tags are case-sensitive.