API Reference

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

Authorization: Bearer isk_your_api_key_here

The full key is shown only once when it is created. Store it securely, never put it in client-side source code, and use a dedicated key for each integration. Deck/language scope controls where new cards are written; it is not a general permission boundary.

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

Paste this prompt into ChatGPT or send it as the user input in an OpenAI API request. It defines the outcome, quality bar, JSON contract, and validation rules expected by the cards endpoint.

Create 20 high-quality flashcards for learning [LANGUAGE] at [LEVEL] level.

Outcome:
- Focus on practical, high-frequency vocabulary and phrases.
- Make each front a single, unambiguous recall cue.
- Make each back a concise translation or answer.
- Include one natural usage example in "context".
- Add 1-3 useful lowercase tags per card.
- Do not create duplicate or near-duplicate cards.

Return exactly one valid JSON object matching this shape:
{
  "deck": "[Language] [Level]",
  "cards": [
    {
      "front": "word, phrase, or question",
      "back": "translation or answer",
      "context": "one natural example with a short clarification if needed",
      "tags": ["level", "topic"]
    }
  ]
}

Output rules:
- Return JSON only: no Markdown fences, commentary, or trailing commas.
- Use double quotes for every key and string.
- Replace every placeholder with real content.
- Verify the JSON is valid before responding.

Replace the bracketed values before sending. Then POST the returned JSON to /api/v1/cards using the Bearer key shown in the request examples below.

OpenAI Responses API with the MCP server

Server-side OpenAI requests can pass the iwill.study key in an HTTP header, so it does not need to appear in the connector URL. Keep both keys in environment variables or a server-side secret manager.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5.6-sol",
  "input": "Use the iwill.study app to create 20 [LANGUAGE] flashcards at [LEVEL] level about [TOPIC]. Use concise recall cues, accurate answers, one natural usage example per card, and useful tags. Avoid duplicates. Save the cards to a deck named \"[Language] [Level] — [Topic]\" and report how many were created or skipped.",
  "tools": [
    {
      "type": "mcp",
      "server_label": "iwill_study",
      "server_description": "Create and manage language-learning flashcards in iwill.study.",
      "server_url": "https://www.iwill.study/api/mcp",
      "headers": {
        "Authorization": "Bearer isk_your_api_key_here"
      },
      "require_approval": "always"
    }
  ]
}'