# API v1 reference

Use the versioned API to automate card management. API keys are managed from your [profile](/profile) and authenticate requests with a Bearer token.

## Authentication

All `/api/v1/*` endpoints expect a Bearer token in the `Authorization` header:

```
Authorization: Bearer rc_lookup_secret
```

Tokens are prefixed `rc_` and consist of a public lookup half and a secret half. Treat the whole string as a secret.

## Examples

### List cards

```bash
curl -H "Authorization: Bearer $REMEMBER_CARDS_API_KEY" \
  "https://remember.cards/api/v1/cards.json?search=%23python&per_page=25"
```

### Create a card

```bash
curl -X POST "https://remember.cards/api/v1/cards.json" \
  -H "Authorization: Bearer $REMEMBER_CARDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"front":"What is spaced repetition?","back":"A review schedule that expands over time.","tags":["learning"]}'
```

### Update a card

```bash
curl -X PATCH "https://remember.cards/api/v1/cards/<card_uuid>.json" \
  -H "Authorization: Bearer $REMEMBER_CARDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"back":"Markdown **is supported**.","tags":["learning","markdown"]}'
```

### Get a card as Markdown

```bash
curl -H "Authorization: Bearer $REMEMBER_CARDS_API_KEY" \
  "https://remember.cards/api/v1/cards/<card_uuid>.md"
```

## Endpoints

| Method | Path | Purpose |
| ------ | ---- | ------- |
| `GET` | `/api/v1/cards.json` | List cards with optional `search`, `tags`, `flagged`, `page`, `per_page` |
| `POST` | `/api/v1/cards.json` | Create a card from JSON |
| `GET` | `/api/v1/cards/<card_uuid>.json` | Fetch one card as JSON |
| `PATCH` | `/api/v1/cards/<card_uuid>.json` | Update card fields from JSON |
| `DELETE` | `/api/v1/cards/<card_uuid>.json` | Delete a card |
| `GET` | `/api/v1/cards/<card_uuid>.md` | Export one card as Markdown |
| `GET` | `/api/v1/tags.json` | List tags currently attached to your cards |

The older `/api` routes are browser endpoints for the web app. External integrations should always use `/api/v1`.