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 Plus or 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.

Include subject metadata to group the batch under an existing subject with the same name or create it. Use subjectId instead to choose an owned subject; null leaves the batch unassigned.

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

{
  "subject": {
    "name": "Business Mathematics",
    "description": "Rates, interest, and loans.",
    "color": "#dce5f9"
  },
  "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). Written questions use responseType: "text" or "number", empty options, answer index 0, and answerText. 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"
      }
    ]
  }
}

Practice Lab kind: "practice"

Use the exam question contract with written responses. Optional acceptedAnswers provide exact wording alternatives; numeric tolerance defines the allowed absolute error. An optional tablecontains a caption, columns, rows, and an answerCell with zero-based row and column. Leave the target cell empty. Context and an image with alt text can illustrate the task. Practice Lab starts in instant feedback mode; all grading stays on the server.

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 materials in numeric title order; repeat subjectId to browse multiple subjects.

POST

/api/v1/materials

Create one new material.

PATCH

/api/v1/materials/bulk

Assign up to 100 owned materials to a subject.

POST

/api/v1/material-sets

Share selected materials at one /shared/{id} link.

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; Plus or Pro accounts may set visibility to private. Explicit private requests are rejected on Free, never silently published.