StudySoda API

Send reviewers, flashcards, and exams from your tools to StudySoda.

Quick start

Create a key

In Settings → Developer API, create a key with the permissions your tool needs.

Prepare your content

Use the OpenAPI specification or the examples below. Ask your AI to preserve sources and explain every correct answer.

Import materials

Import a batch and open the returned material IDs in StudySoda. New materials are public by default. Private content requires Pro.

Your first import

POST /api/v1/import

Use a server-side script or a trusted AI assistant. Store the key in an environment variable or secret store.

curl -X POST 'https://your-domain.com/api/v1/import' \
  -H 'Authorization: Bearer YOUR_STUDYSODA_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: chapter-16-import-v1' \
  --data @materials.json

Save this JSON as materials.json, or use it as the materials variable in the code examples:

materials.json

{
  "materials": [
    {
      "title": "Simple interest essentials",
      "description": "A quick deck prepared by my study assistant.",
      "kind": "flashcards",
      "visibility": "public",
      "tags": [
        "Business Mathematics"
      ],
      "content": {
        "cards": [
          {
            "id": "principal",
            "front": "What is principal?",
            "back": "The original amount borrowed or invested.",
            "explanation": "Simple interest is calculated on this original amount."
          },
          {
            "id": "simple-interest",
            "front": "What is the simple-interest formula?",
            "back": "I = P × R × T",
            "explanation": "Use the annual rate as a decimal and time in years."
          }
        ]
      }
    }
  ]
}

Material formats

Every material has a title, kind, content, optional description, tags, subject, and visibility.

Reviewers kind: "note"

Put your reviewer in content.markdown. Markdown headings, formulas in plain text, examples, lists, links, and tables are supported.

{
  "title": "Chapter 16 reviewer",
  "kind": "note",
  "content": {
    "markdown": "## Simple interest\n\n**I = P × R × T**\n\nUse years for T."
  }
}

Flashcards kind: "flashcards"

Use content.cards. Each card needs a unique ID, front, and back. Explanation and source are optional. Maximum 1,000 cards.

Exams kind: "quiz"

Use content.questions. Each question needs an ID, prompt, 2–6 unique options, a zero-based correct-answer index, explanation, and kind (concept or calculation). Maximum 500 questions.

{
  "title": "Interest check",
  "kind": "quiz",
  "content": {
    "conventions": "Round final money to cents.",
    "questions": [
      {
        "id": "q1",
        "prompt": "What is the interest on $1,000 at 5% for one year?",
        "options": [
          "$5",
          "$50",
          "$500",
          "$1,050"
        ],
        "answer": 1,
        "explanation": "I = P × R × T = 1,000 × 0.05 × 1 = $50.",
        "kind": "calculation",
        "source": "Your lesson, page 1"
      }
    ]
  }
}

Link materials by topic

Create a topic with POST /api/v1/topics, then include its topicId when creating or importing each reviewer, deck, and exam. All linked materials must belong to you.

{
  "title": "Simple Interest",
  "description": "Principal, rates, and maturity value."
}

Use GET /api/v1/materials/{id}/related to read visible companion materials.

API essentials

GET

/api/v1/materials

List or search accessible materials.

POST

/api/v1/materials

Create one new material.

GET

/api/v1/materials/{id}

Read a material you can access.

PATCH

/api/v1/materials/{id}

Update a material you own.

DELETE

/api/v1/materials/{id}

Delete a material you own.

POST

/api/v1/import

Import up to 50 materials atomically.

GET

/api/v1/export

Export your original content.

GET / POST

/api/v1/subjects

Read subjects or create your own.

Full schemas, error responses, scopes, and account-only study endpoints are in the OpenAPI specification.

Request rules

Scoped and revocable
Read and write are separate permissions. Keys never manage account credentials or impersonate browser sessions.
Retry without duplicate content
Use the same Idempotency-Key header when retrying an unchanged import. A reused key with different content returns 409.
Validation before anything is saved
Invalid imports fail as a whole. Successful responses contain data; errors include a code and message. Respect 429 responses and Retry-After.
Visibility follows your plan
Content defaults to public. Free accounts cannot create or edit private materials; Pro accounts may set visibility to private. Explicit private requests are rejected on Free, never silently published.