Tutro developers

Build on Tutro.

One REST API, one MCP server, one credit balance. Drop your API key into a curlcall, the official TypeScript SDK source, or an MCP client with custom header support — it all hits the same pipelines that power tutro.ai. Every call bills against your regular credits; there's no separate developer plan.

Quickstart

Your first call

Once you have a key from Settings → Developer, every endpoint lives under https://app.tutro.ai/api/v1. Authenticate with a bearer token:

bash
curl https://app.tutro.ai/api/v1/credits \
  -H "Authorization: Bearer tutr_xxx"
TypeScript SDK

@tutro/sdk

The TypeScript client source is in packages/sdk in the Tutro repository. It is not published to npm yet. Use the REST quickstart above for integrations today. Keep API keys in server-side code.

ts
import { TutroClient } from "@tutro/sdk";

const tutro = new TutroClient({ apiKey: process.env.TUTRO_API_KEY! });

// Kick off a lesson
const { lessonId } = await tutro.lessons.create({
  topic: "Photosynthesis in plants",
  gradeLevel: "5",
  shareWithCommunity: true, // Only after the user agrees to publish
  generateSlides: false, // Text-only lesson
});

// Poll until it's ready
while (true) {
  const { lesson } = await tutro.lessons.get(lessonId);
  if (lesson.status === "ready") break;
  if (lesson.status === "failed") throw new Error("Lesson generation failed");
  await new Promise((r) => setTimeout(r, 3000));
}
MCP

Connect Tutro to your MCP client

  1. Create a Tutro API key. Keep it private.
  2. In your client, add a remote MCP server using Streamable HTTP.
  3. Paste this URL and set the Authorization header to Bearer YOUR_TUTRO_API_KEY.
https://app.tutro.ai/api/mcp

Then ask: “What is my Tutro credit balance?” This check is free.

Your client must support custom Authorization headers. URL-only OAuth sign-in is not available yet.

Cursor configuration (replace the API key placeholder):

json
{
  "mcpServers": {
    "tutro": {
      "url": "https://app.tutro.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer tutr_xxx"
      }
    }
  }
}

For Claude Code, run:

bash
claude mcp add --transport http tutro https://app.tutro.ai/api/mcp \
  --header "Authorization: Bearer YOUR_TUTRO_API_KEY"

For VS Code, add this to .vscode/mcp.json. The key is prompted and stored as a secret:

json
{
  "inputs": [{ "type": "promptString", "id": "tutro-key", "description": "Tutro API key", "password": true }],
  "servers": {
    "tutro": {
      "type": "http",
      "url": "https://app.tutro.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${input:tutro-key}" }
    }
  }
}

For Claude Desktop, remote connectors that require OAuth cannot use a Tutro API key directly. Use a client with custom header support.

Exposed tools: list_lessons, get_lesson, create_lesson, list_learners, credits_balance, get_lesson_accuracy, and review_lesson_accuracy.

Reference

REST endpoints

GET/api/v1/credits
Returns the API key owner's current credit balance.
GET/api/v1/lessons?limit=20
Lists the caller's lessons (newest first).
POST/api/v1/lessons
Body: { topic, gradeLevel, subject?, learnerId?, shareWithCommunity?, animated?, animationQuality?, generateSlides?, quizOnly?, songMode?, songStyle?, language?, plannerTier?, testDate?, narratorVoice? }. Kicks off a lesson and returns lessonId. Illustrated lessons require at least 400 credits; animation adds a quality-dependent budget. Free starter lessons require explicit community sharing consent. Paid plans can choose private lessons. Actual usage is metered per asset.
GET/api/v1/lessons/:id
Fetches a single lesson with its full plan.
GET/api/v1/learners
Lists learners in the caller's family.
Billing

One balance, metered per asset

API and MCP calls don't have a separate plan. Every credit-consuming operation (LLM tokens, image generation, TTS, video render) bills the API key owner's balance at the same per-unit rates the web app uses. Free operations (listing lessons, checking balance) stay free. Top up or upgrade from Settings → Billing.

Something missing?

We ship endpoints on demand. Email us at api@tutro.ai with what you're trying to build.