API Reference

Programmatically create decks, add flashcards, and import files into your iwill.study account.

Authentication

All API requests require a Bearer token. Generate an API key in Settings → API Keys.

Authorization: Bearer isk_your_api_key_here

Base URL

https://www.iwill.study/api/v1

Rate Limits

Plan	Cards via API	Decks
Free	100 cards/day	5 decks
Pro	Unlimited	Unlimited

Endpoints

GET/api/v1/decks

List all decks belonging to the authenticated user, with card counts.

Authentication

Bearer token (API key)

Response

{
  "decks": [
    {
      "id": "uuid",
      "title": "Spanish B1",
      "description": "",
      "language": "Spanish",
      "source": "api",
      "created_at": "2026-03-14T...",
      "card_count": 42
    }
  ]
}

POST/api/v1/decks

Create a new empty deck.

Authentication

Bearer token (API key)

Request Body

Field	Type	Required	Description
`title`	string	Yes	Deck title (max 200 chars)
`description`	string	No	Deck description
`language`	string	No	Target language (e.g. "Spanish")

Response

{
  "deck": {
    "id": "uuid",
    "title": "Spanish B1",
    "description": "",
    "language": "Spanish",
    "source": "api",
    "created_at": "2026-03-14T..."
  }
}

DELETE/api/v1/decks

Delete a deck and all its cards.

Authentication

Bearer token (API key)

Query Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Deck ID to delete

Response

{ "success": true }

GET/api/v1/cards

List all cards in a specific deck.

Authentication

Bearer token (API key)

Query Parameters

Parameter	Type	Required	Description
`deck_id`	string	Yes	Deck ID to fetch cards from

Response

{
  "cards": [
    {
      "id": "uuid",
      "front": "however",
      "back": "sin embargo",
      "tags": ["b1", "connectors"],
      "context": "Formal writing: 'The results, however, were unexpected.'",
      "source": "api",
      "created_at": "2026-03-14T..."
    }
  ]
}

POST/api/v1/cards

Add cards to a deck. Specify an existing deck by ID, or provide a title to find-or-create a deck.

Authentication

Bearer token (API key)

Request Body

Field	Type	Required	Description
`deck_id`	string	No	Existing deck UUID. Use this to add cards to a specific deck.
`deck`	string	No	Deck title (max 200 chars). Creates deck if not found. Required if deck_id is not provided.
`cards`	array	Yes	Array of card objects (max 500 per request)
`cards[].front`	string	Yes	Front side text (max 5000 chars)
`cards[].back`	string	Yes	Back side text (max 5000 chars)
`cards[].tags`	string[]	No	Optional tags for the card
`cards[].context`	string	No	Usage examples, cultural notes, or contextual info (max 10,000 chars)

Response

{
  "deck_id": "uuid",
  "created": 2,
  "skipped": 1
}

Duplicates are automatically skipped — cards with the same front text (case-insensitive) already in the deck won't be added again. The response includes a 'skipped' count. Provide either deck_id or deck (title), not both. Free plan: max 100 cards/day via API.

PATCH/api/v1/cards

Update or move cards. Use this to move cards between decks (preserving review history), edit card content, or update context and tags.

Authentication

Bearer token (API key)

Request Body

Field	Type	Required	Description
`card_ids`	string[]	Yes	Array of card UUIDs to update (max 500)
`updates.deck_id`	string	No	Target deck UUID — moves cards to this deck
`updates.front`	string	No	New front text (max 5,000 chars)
`updates.back`	string	No	New back text (max 5,000 chars)
`updates.tags`	string[]	No	New tags array
`updates.context`	string \| null	No	New context/examples (max 10,000 chars), or null to clear

Response

{ "updated": 3 }

Moving cards between decks preserves all FSRS review history. You can combine a move with field updates in a single request.

POST/api/v1/import

Import flashcards from an Anki (.apkg) or CSV/TSV file.

Authentication

Bearer token (API key)

Request Body

Field	Type	Required	Description
`file`	File	Yes	Upload via multipart/form-data. Accepted: .apkg, .csv, .tsv, .txt

Response

{
  "deck_id": "uuid",
  "imported": 150
}

CSV files should have two columns: front and back. The filename (without extension) is used as the deck name.

Error Codes

Status	Meaning
`400`	Bad request — invalid or missing parameters
`401`	Unauthorized — missing or invalid API key
`404`	Not found — resource doesn't exist or doesn't belong to you
`429`	Rate limited — daily card limit exceeded (free plan)
`500`	Server error — please try again or contact support