API Reference

Build integrations with the Repple API. Manage your decks, cards, and study sessions programmatically.

Base URL https://repple.sh/api/v1

Authentication

All API requests require a valid API key. You can create and manage API keys from your Settings page.

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer pk_your_api_key_here

API keys are prefixed with pk_ and grant full access to your account. Keep them secret and never expose them in client-side code.

Example
curl https://repple.sh/api/v1/decks \
  -H "Authorization: Bearer pk_abc123def456..."

MCP

Plug Repple into any MCP client, Claude Desktop, ChatGPT, and turn conversations into flashcards from wherever you work. Authentication happens over OAuth the first time your client connects; no API key needed.

https://repple.sh/mcp

Tools

  • list_decksList the user's decks with card counts.
  • list_cardsList accepted cards in a deck, with optional substring filter.
  • create_deckCreate a deck (or nested path via "::").
  • create_cardCreate a single flashcard with an explicit front and back.
  • generate_flashcardsGenerate a batch of cards from a conversation transcript. Cards land in the inbox.
claude_desktop_config.json
{
  "mcpServers": {
    "repple": {
      "url": "https://repple.sh/mcp"
    }
  }
}

Decks

GET /decks
List all decks for the authenticated user.
Request
curl https://repple.sh/api/v1/decks \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "decks": [
    {
      "id": "uuid",
      "name": "Spanish",
      "parent_id": null,
      "icon": null,
      "created_at": "2025-01-15T10:00:00.000Z"
    }
  ]
}
GET /decks/:id
Get a single deck by ID.
Path parameters
NameTypeDescription
idrequired string Deck ID
Request
curl https://repple.sh/api/v1/decks/:id \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "id": "uuid",
  "name": "Spanish",
  "parent_id": null,
  "icon": null,
  "created_at": "2025-01-15T10:00:00.000Z"
}
POST /decks
Create a new deck. Use "::" in the name to create nested decks (e.g. "Languages::Spanish").
Body parameters
NameTypeDescription
namerequired string Deck name. Use "::" for nesting.
Request
curl -X POST https://repple.sh/api/v1/decks \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Languages::Spanish"}'
Response
{
  "id": "uuid",
  "name": "Spanish",
  "parent_id": "parent-uuid",
  "icon": null,
  "created_at": "2025-01-15T10:00:00.000Z"
}
PATCH /decks/:id
Update a deck's name or icon.
Path parameters
NameTypeDescription
idrequired string Deck ID
Body parameters
NameTypeDescription
nameoptional string New deck name
iconoptional string | null Emoji icon (max 10 chars), or null to remove
Request
curl -X PATCH https://repple.sh/api/v1/decks/:id \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "French"}'
Response
{
  "id": "uuid",
  "name": "French",
  "parent_id": null,
  "icon": null,
  "created_at": "2025-01-15T10:00:00.000Z"
}
DELETE /decks/:id
Delete a deck and all its cards.
Path parameters
NameTypeDescription
idrequired string Deck ID
Request
curl -X DELETE https://repple.sh/api/v1/decks/:id \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{ "success": true }

Cards

GET /decks/:id/cards
List cards in a deck (includes cards from sub-decks). Results are paginated.
Path parameters
NameTypeDescription
idrequired string Deck ID
Query parameters
NameTypeDescription
pageoptional integer Page number (default: 1)
limitoptional integer Cards per page (1-100, default: 24)
Request
curl https://repple.sh/api/v1/decks/:id/cards \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "flashcards": [
    {
      "id": "uuid",
      "deck_id": "uuid",
      "template_id": "uuid",
      "field_values": { "Front": "Hola", "Back": "Hello" },
      "scheduling": { ... },
      "created_at": "2025-01-15T10:00:00.000Z"
    }
  ],
  "currentPage": 1,
  "totalPages": 5,
  "totalCount": 48
}
GET /cards/due
Get cards that are due for review. Optionally filter by deck.
Query parameters
NameTypeDescription
deck_idoptional string Filter by deck ID (includes sub-decks)
limitoptional integer Maximum number of cards to return
Request
curl https://repple.sh/api/v1/cards/due \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
[
  {
    "id": "uuid",
    "deck_id": "uuid",
    "field_values": { "Front": "Hola", "Back": "Hello" },
    "scheduling": { ... }
  }
]
GET /cards/:id
Get a single card by ID.
Path parameters
NameTypeDescription
idrequired string Card ID
Request
curl https://repple.sh/api/v1/cards/:id \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "id": "uuid",
  "deck_id": "uuid",
  "template_id": "uuid",
  "field_values": { "Front": "Hola", "Back": "Hello" },
  "scheduling": { ... },
  "created_at": "2025-01-15T10:00:00.000Z"
}
POST /cards
Create a new card. Uses the Basic template if none is specified.
Body parameters
NameTypeDescription
deck_idrequired string Deck ID (or "no_deck" for unsorted)
field_valuesrequired object Map of field name to value (e.g. {"Front": "...", "Back": "..."})
template_idoptional string Template ID (defaults to Basic)
tag_idsoptional string[] Array of tag IDs to attach
Request
curl -X POST https://repple.sh/api/v1/cards \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deck_id": "DECK_ID", "field_values": {"Front": "Hola", "Back": "Hello"}}'
Response
{
  "id": "uuid",
  "deck_id": "uuid",
  "template_id": "uuid",
  "field_values": { "Front": "Hola", "Back": "Hello" },
  "scheduling": { ... },
  "created_at": "2025-01-15T10:00:00.000Z"
}
PATCH /cards/:id
Update a card's fields, template, deck, or tags. Field values are merged with existing values unless the template changes.
Path parameters
NameTypeDescription
idrequired string Card ID
Body parameters
NameTypeDescription
field_valuesoptional object Map of field name to value
template_idoptional string New template ID
deck_idoptional string Move to a different deck
tag_idsoptional string[] Replace all tags with these IDs
Request
curl -X PATCH https://repple.sh/api/v1/cards/:id \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_values": {"Back": "Hi"}}'
Response
{
  "id": "uuid",
  "deck_id": "uuid",
  "template_id": "uuid",
  "field_values": { "Front": "Hola", "Back": "Hi" },
  "scheduling": { ... },
  "created_at": "2025-01-15T10:00:00.000Z"
}
DELETE /cards/:id
Delete a card.
Path parameters
NameTypeDescription
idrequired string Card ID
Request
curl -X DELETE https://repple.sh/api/v1/cards/:id \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{ "success": true }
POST /cards/:id/review
Submit a review for a card. Uses FSRS to schedule the next review.
Path parameters
NameTypeDescription
idrequired string Card ID
Body parameters
NameTypeDescription
ratingrequired string | number "again", "hard", "good", "easy" (or numeric 1-4)
schedulingKeyoptional string Scheduling key for multi-schedule cards (default: "0")
Request
curl -X POST https://repple.sh/api/v1/cards/:id/review \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": "good"}'
Response
{
  "flashcard": {
    "id": "uuid",
    "scheduling": { ... }
  },
  "review": {
    "id": "uuid",
    "rating": "good",
    "review": "2025-01-15T10:00:00.000Z",
    "elapsed_days": 3
  }
}

Tags

GET /tags
List all tags for the authenticated user.
Request
curl https://repple.sh/api/v1/tags \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "tags": [
    { "id": "uuid", "name": "vocabulary", "user_id": "uuid" }
  ]
}
POST /tags
Create a new tag (or return existing one with the same name).
Body parameters
NameTypeDescription
namerequired string Tag name (max 50 chars)
Request
curl -X POST https://repple.sh/api/v1/tags \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "vocabulary"}'
Response
{
  "id": "uuid",
  "name": "vocabulary",
  "user_id": "uuid"
}
DELETE /tags/:id
Delete a tag. This removes it from all cards.
Path parameters
NameTypeDescription
idrequired string Tag ID
Request
curl -X DELETE https://repple.sh/api/v1/tags/:id \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{ "success": true }

Templates

GET /templates
List all templates (including the system "Basic" template).
Request
curl https://repple.sh/api/v1/templates \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "templates": [
    {
      "id": "uuid",
      "name": "Basic",
      "fields": [
        { "id": "Front", "name": "Front", "type": "text" },
        { "id": "Back", "name": "Back", "type": "text" }
      ],
      "front_fields": ["Front"],
      "back_fields": ["Back"],
      "auto_reverse": false
    }
  ]
}
GET /templates/:id
Get a single template by ID.
Path parameters
NameTypeDescription
idrequired string Template ID
Request
curl https://repple.sh/api/v1/templates/:id \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "id": "uuid",
  "name": "Basic",
  "fields": [
    { "id": "Front", "name": "Front", "type": "text" },
    { "id": "Back", "name": "Back", "type": "text" }
  ],
  "front_fields": ["Front"],
  "back_fields": ["Back"],
  "auto_reverse": false
}
POST /templates
Create a new card template.
Body parameters
NameTypeDescription
namerequired string Template name
fieldsrequired object[] Array of field objects with id, name, and type ("text" or "image")
front_fieldsrequired string[] Fields shown on the front
back_fieldsrequired string[] Fields shown on the back
auto_reverseoptional boolean Generate a reverse card (default: false)
Request
curl -X POST https://repple.sh/api/v1/templates \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vocabulary", "fields": [{"id": "Word", "name": "Word", "type": "text"}, {"id": "Definition", "name": "Definition", "type": "text"}, {"id": "Example", "name": "Example", "type": "text"}], "front_fields": ["Word"], "back_fields": ["Definition", "Example"]}'
Response
{
  "id": "uuid",
  "name": "Vocabulary",
  "fields": [
    { "id": "Word", "name": "Word", "type": "text" },
    { "id": "Definition", "name": "Definition", "type": "text" },
    { "id": "Example", "name": "Example", "type": "text" }
  ],
  "front_fields": ["Word"],
  "back_fields": ["Definition", "Example"],
  "auto_reverse": false
}
PATCH /templates/:id
Update a template. System templates ("Basic") cannot be modified.
Path parameters
NameTypeDescription
idrequired string Template ID
Body parameters
NameTypeDescription
nameoptional string New name
fieldsoptional object[] Array of field objects with id, name, and type
front_fieldsoptional string[] Fields shown on the front
back_fieldsoptional string[] Fields shown on the back
auto_reverseoptional boolean Generate a reverse card
Request
curl -X PATCH https://repple.sh/api/v1/templates/:id \
  -H "Authorization: Bearer pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Vocabulary"}'
Response
{
  "id": "uuid",
  "name": "Updated Vocabulary",
  "fields": [
    { "id": "Word", "name": "Word", "type": "text" },
    { "id": "Definition", "name": "Definition", "type": "text" },
    { "id": "Example", "name": "Example", "type": "text" }
  ],
  "front_fields": ["Word"],
  "back_fields": ["Definition", "Example"],
  "auto_reverse": false
}
DELETE /templates/:id
Delete a template and all cards using it. System templates cannot be deleted.
Path parameters
NameTypeDescription
idrequired string Template ID
Request
curl -X DELETE https://repple.sh/api/v1/templates/:id \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "success": true,
  "cardsDeleted": 12
}

Stats

GET /stats
Get overall study statistics including card counts, review history, and daily activity.
Request
curl https://repple.sh/api/v1/stats \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "streak": 3,
  "retention": 92,
  "totalCards": 150,
  "today": {
    "reviewed": 25,
    "studyTimeMs": 180000
  },
  "dailyActivity": [
    { "date": "2025-01-15", "count": 25 }
  ]
}
GET /activity
Get daily review activity (subset of stats).
Request
curl https://repple.sh/api/v1/activity \
  -H "Authorization: Bearer pk_YOUR_KEY"
Response
{
  "dailyActivity": [
    { "date": "2025-01-15", "count": 25 }
  ]
}