Agent Self-Service Onboarding | TutorFlow Agent Platform Docs

Overview

TutorFlow Agent Platform is built for autonomous agents. An AI agent can:

Discover the service via a public manifest.
Register a workspace and receive an API key in one POST.
Spend the $1.00 free trial credit immediately, no email verification, no payment method, no human in the loop.
When trial credits run out, request a checkout URL and forward it to a human (Slack, email, anywhere) for payment.

Using Claude or another MCP-compatible agent? Connect via the MCP Integration guide instead. The MCP server exposes onboarding, billing, pricing, evaluations, and courses as structured tools. Use REST for modules, tests, slides, and videos.

Agent Quick Reference

Step	Endpoint	Auth	Required for trial?
1. Discover	`GET /v1/platform/.well-known/agent.json`	None	Optional
2. Register	`POST /v1/platform/agent/register`	None (5/IP/hour)	Yes
3. Use APIs	`POST /v1/platform/evaluations`, `/v1/platform/courses`, `/v1/platform/modules`, `/v1/platform/tests`, `/v1/platform/slides`, `/v1/platform/videos`	API key	Yes
4. Check balance	`GET /v1/platform/agent/account`	API key	Optional
5. (Before paid top-up) Verify email if needed	`POST /v1/platform/agent/verify-email/resend`	API key	No
6. (When credits low) Request checkout	`POST /v1/platform/agent/billing/session`	API key	No

The simplest happy path is step 2 → step 3. Steps 1, 4, 5, 6 are optional or deferred until you need them.

1. Discovery (Optional)

Agents discover the platform by fetching the public manifest. You can skip this step and hard-code the registration endpoint if you prefer.

curl https://api.tutorflow.io/v1/platform/.well-known/agent.json

Response:

{
  "schema": "https://tutorflow.io/agent-manifest/v2",
  "name": "TutorFlow Agent Platform",
  "description": "AI-powered teaching content and evaluation APIs for education technology",
  "baseUrl": "https://api.tutorflow.io/v1/platform",
  "auth": { "type": "bearer", "prefix": "tf_platform_", "header": "Authorization" },
  "registration": {
    "endpoint": "/v1/platform/agent/register",
    "method": "POST",
    "requiredFields": ["name", "slug"],
    "optionalFields": ["email", "agentIdentity"]
  },
  "services": ["evaluation", "course", "module", "test", "slide", "video"],
  "capabilities": {
    "evaluation": { "endpoint": "/v1/platform/evaluations", "unit": "request",       "unitPriceUsd": 0.02 },
    "course":     { "endpoint": "/v1/platform/courses",     "unit": "lesson",        "unitPriceUsd": 0.05 },
    "module":     { "endpoint": "/v1/platform/modules",     "unit": "lesson",        "unitPriceUsd": 0.05 },
    "test":       { "endpoint": "/v1/platform/tests",       "unit": "item",          "unitPriceUsd": 0.015 },
    "slide":      { "endpoint": "/v1/platform/slides",      "unit": "slide",         "unitPriceUsd": 0.03 },
    "video":      { "endpoint": "/v1/platform/videos",      "unit": "scene",         "unitPriceUsd": 0.04 }
  },
  "addOns": {
    "slide_image":          { "endpoint": "/v1/platform/slides/edit/:editToken/generate/image",          "unit": "image",        "unitPriceUsd": 0.07 },
    "video_tts_regenerate": { "endpoint": "/v1/platform/videos/edit/:editToken/scenes/:sceneId/tts",     "unit": "call",         "unitPriceUsd": 0.02 },
    "video_render":         { "trigger": "render-callback",                                              "unit": "video_minute", "unitPriceUsd": 0.15 }
  },
  "trial": {
    "creditsUsd": 1,
    "emailVerificationRequiredForTrial": false,
    "emailVerificationRequiredForBilling": true
  },
  "pricing": {
    "endpoint": "/v1/platform/pricing-catalog",
    "currency": "USD",
    "model": "per_unit"
  },
  "paymentMethods": {
    "topUp": {
      "endpoint": "POST /v1/platform/agent/billing/session",
      "minimumUsd": 5,
      "maximumUsd": 5000,
      "description": "Returns a TutorFlow-hosted checkout page URL where the human operator can choose an amount and pay through Stripe."
    }
  },
  "docs": "https://tutorflow.io/agent-platform/docs",
  "health": "/v1/platform/health"
}

2. Registration

Send a single POST request. No authentication required.

Field	Type	Required	Description
`name`	`string`	Yes	Workspace display name
`slug`	`string`	Yes	Unique URL-safe identifier. Lowercase letters, numbers, and hyphens only. Cannot start or end with a hyphen.
`email`	`string`	No	Contact email. Required before billing/payment, not required for the trial. Include it at registration if the agent may need paid top-ups; there is no public self-serve endpoint to add it later.
`agentIdentity`	`string`	No	Free-form identity string (e.g. `"claude-opus-4 via LangChain"`). Helps TutorFlow understand which models hit the API.

curl -X POST https://api.tutorflow.io/v1/platform/agent/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Tutor",
    "slug": "my-ai-tutor",
    "email": "agent@example.com",
    "agentIdentity": "claude-opus-4 via LangChain"
  }'

Response (201 Created):

{
  "organizationId": "uuid",
  "apiKey": "tf_platform_a1b2c3d4e5f6g7h8i9j0klmn...",
  "keyPrefix": "tf_platform_a1b2c3d4e5f6",
  "trialCredits": 100,
  "message": "Store your API key securely. It will not be shown again.",
  "requiresEmailVerification": true,
  "verifyEmailResendEndpoint": "POST /v1/platform/agent/verify-email/resend",
  "nextSteps": {
    "createSlide": "POST /v1/platform/slides",
    "createVideo": "POST /v1/platform/videos",
    "accountInfo": "GET /v1/platform/agent/account"
  }
}

trialCredits is in cents: 100 = $1.00.

requiresEmailVerification: true is informational. It tells the agent that verification is pending but does not block the trial. The flag becomes relevant only when the agent later tries to add billing or pay with USDC.

If you omit email, trial usage still works, but paid top-up flows cannot be completed through public agent endpoints because verification and billing both need an email on file.

Rate limit: 5 registrations per IP per hour.

Critical for agents: store apiKey immediately. The hashed value is kept; the raw key is never returned again.

3. Start Making Generation Calls (Trial)

You now have $1.00 in credits. With the API key from step 2, call any generation endpoint immediately. No verification, no card.

# Evaluation, grade an answer
curl -X POST https://api.tutorflow.io/v1/platform/evaluations \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationType": "open_ended",
    "questionText": "What causes seasons on Earth?",
    "learnerAnswer": "The tilt of Earth axis causes seasons.",
    "language": "en",
    "maxScore": 10
  }'
 
# Course, generate a curriculum
curl -X POST https://api.tutorflow.io/v1/platform/courses \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Beginner Python course", "lessonCount": 5 }'
 
# Module, generate one reusable standalone lesson
curl -X POST https://api.tutorflow.io/v1/platform/modules \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Data privacy basics for managers", "hasQuiz": true }'
 
# Slide, generate a TipTap deck
curl -X POST https://api.tutorflow.io/v1/platform/slides \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Mediterranean diet overview", "slideCount": 6 }'
 
# Video, generate a narrated short
curl -X POST https://api.tutorflow.io/v1/platform/videos \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "What is photosynthesis?", "sceneCount": 4 }'
 
# Test, generate an assessment
curl -X POST https://api.tutorflow.io/v1/platform/tests \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Quick math quiz for 5th graders", "itemCount": 10 }'

Response shape differs by API. Courses, tests, slides, and videos return shareable URLs for review or delivery. Modules return a publicUrl and direct module fields. Evaluations return grading and learner data instead of content URLs. See the per-API references for details:

4. Check Account Info

curl https://api.tutorflow.io/v1/platform/agent/account \
  -H "Authorization: Bearer tf_platform_..."

{
  "organizationId": "uuid",
  "name": "My AI Tutor",
  "slug": "my-ai-tutor",
  "status": "ACTIVE",
  "creditBalance": 88,
  "rateLimitPerMinute": 1000,
  "createdAt": "2026-04-25T00:00:00.000Z"
}

creditBalance is in cents. Watch this drop as you generate. When it approaches 0, time to top up (step 5).

5. Billing Setup (After Trial Credits)

When creditBalance is low or zero, agents should not block on a synchronous human handoff. The recommended pattern:

Call POST /v1/platform/agent/billing/session to mint a checkout URL.
Forward the URL to the human via your normal channel (Slack, email, in-product chat).
Continue any work that does not require new API calls.
Resume API calls once GET /v1/platform/agent/billing/status reports hasPaymentMethod: true or creditBalance > 0.

Email verification is enforced at this step. If the workspace email is unverified, the billing session call returns email_verification_required (HTTP 403). Resend the verification email first (POST /v1/platform/agent/verify-email/resend), have the recipient click the link, then retry the billing session.

5.1 Request a Billing Session

curl -X POST https://api.tutorflow.io/v1/platform/agent/billing/session \
  -H "Authorization: Bearer tf_platform_..."

Response:

{
  "url": "https://tutorflow.io/agent-platform/checkout?token=xxx",
  "sessionId": "checkout-token-uuid"
}

Forward url to the human. sessionId is the TutorFlow checkout token, not a Stripe cs_... session ID. The hosted page lets the human pick a top-up amount ($5 minimum, $5,000 maximum) and complete payment via Stripe. Card data never passes through your agent.

5.2 Check Billing Status

curl https://api.tutorflow.io/v1/platform/agent/billing/status \
  -H "Authorization: Bearer tf_platform_..."

{
  "hasPaymentMethod": true,
  "cardBrand": "visa",
  "cardLast4": "4242",
  "creditBalance": 5000,
  "billingMode": "internal_invoice"
}

Alternative: Pay with USDC (x402)

If your agent has a USDC balance on Base network, it can use x402 to add credits without registering a card. When credits are exhausted and the workspace email is verified, API calls can return 402 Payment Required with an x402 payload describing the deposit:

{
  "error": {
    "code": "payment_required",
    "message": "Credits exhausted. Pay with USDC via x402 or register a payment method.",
    "x402": {
      "scheme": "exact",
      "network": "eip155:8453",
      "price": "$0.01",
      "payTo": "0x...",
      "description": "TutorFlow API request payment",
      "mimeType": "application/json",
      "resource": "POST /v1/platform/evaluations"
    },
    "billingSessionUrl": "POST /v1/platform/agent/billing/session",
    "status": 402
  }
}

Send USDC to payTo, wait for on-chain settlement, then retry the request with an X-Payment header. The paid amount is added to the workspace credit balance. The current x402 requirement is a $0.01 deposit, so a generation request that costs more than the deposited balance can still return platform_credits_exhausted on retry. Top up through the billing session or repeat the x402 deposit flow until creditBalance covers the request.

x402 support is available when x402.enabled is true in GET https://api.tutorflow.io/v1/platform/.well-known/agent.json.

6. Email Verification (When Needed)

Verification is not required for trial generation. It is required before any paid path (Stripe checkout, USDC top-up). Trigger or resend the verification email with:

curl -X POST https://api.tutorflow.io/v1/platform/agent/verify-email/resend \
  -H "Authorization: Bearer tf_platform_..."

The recipient clicks the link in the email, which calls GET /v1/platform/agent/verify-email?token=.... Once verified, billing endpoints unblock.

Endpoint Summary

Method	Endpoint	Auth	Description
`GET`	`/.well-known/agent.json`	None	Service discovery manifest
`POST`	`/agent/register`	None (IP throttled)	Self-registration
`GET`	`/agent/verify-email?token=`	None	Verify email address
`POST`	`/agent/verify-email/resend`	API Key	Resend verification email
`POST`	`/agent/billing/session`	API Key	Get checkout page URL
`GET`	`/agent/billing/status`	API Key	Billing status
`GET`	`/agent/account`	API Key	Account info + credit balance
`GET`	`/agent/checkout?token=`	None	Validate a checkout token
`POST`	`/agent/checkout`	None	Create Stripe session from checkout token