Agent Self-Service API

Use this page to look up every field of the registration, account, email verification, and billing routes an agent calls on its own.

Overview

These routes are called by agents, without a person. Registration and discovery are public. The account and billing routes take the live Content key that POST /v1/platform/agent/register returns as contentApiKey, which has full access. A test key or a narrower key gets 403 platform_content_key_too_narrow; a missing or unknown key gets 401 platform_invalid_api_key. A legacy tf_platform_ key also works on these account routes, and on no content route.

On these routes, organizationId is the workspace id, not the id of the TutorFlow organization that owns the classrooms and the credit balance. Balances are in credits, except creditBalance, which is in cents.

Content work itself happens on the Content API, under /v1/content/classrooms/{classroomId}.

Base URL:

https://api.tutorflow.io/v1/platform

GET /v1/platform/pricing-catalog

Return the live pricing catalog, generated from the credit amounts the backend charges at 2 US cents per credit. See Pricing and Billing for every entry.

Authentication

None.

Response Fields

The response is an array.

GET /v1/platform/.well-known/agent.json

Return the discovery manifest agents can use to find registration, pricing, capability, add-on, and top-up metadata.

Authentication

None.

Stable Fields

The manifest and GET /v1/platform/pricing-catalog quote prices from the same source, and both price the Content API calls. In capabilities, creating a video is free (unitPriceUsd 0); its narration and render are the video_narration ($0.02 per scene) and video_render ($0.10 per render) add-ons. capabilities.slide carries imagePagePriceUsd (0.06) next to its text page price. See Pricing and Billing for every price.

POST /v1/platform/agent/register

Create an agent account and return its key. One transaction creates the account, the TutorFlow organization behind it, a default classroom, and 50 trial credits; then the tf_content_ key is issued.

Authentication

None. Register is limited to 5 attempts per client IP per rolling hour, and failed attempts such as a 422 count too. Register once and keep the key. Every answer carries X-RateLimit-* headers; over the limit the answer is 429 platform_rate_limit_exceeded with a Retry-After header and error.retryAfterSeconds.

Request Body

Example Request

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 via mcp"
  }'

Response

{
  "organizationId": "0f7a5db7-9f9d-4a46-9f5b-5b8f8ad73001",
  "apiKey": null,
  "keyPrefix": null,
  "contentApiKey": "tf_content_...",
  "contentApiKeyPrefix": "tf_content_a1b2c3d4",
  "defaultClassroomId": "00000000-0000-4000-8000-000000000010",
  "contentApiBaseUrl": "https://api.tutorflow.io/v1/content",
  "trialCredits": 100,
  "trialContentCredits": 50,
  "message": "Store contentApiKey securely; it will not be shown again. It signs every Content API call and the account routes under /v1/platform/agent. apiKey is null: legacy tf_platform_ keys are no longer issued.",
  "requiresEmailVerification": true,
  "verifyEmailResendEndpoint": "POST /v1/platform/agent/verify-email/resend",
  "nextSteps": {
    "createCourse": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/courses",
    "listCourses": "GET /v1/content/classrooms/00000000-0000-4000-8000-000000000010/courses",
    "createSlide": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/slides",
    "createVideo": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/videos",
    "accountInfo": "GET /v1/platform/agent/account"
  }
}

Store contentApiKey immediately. It is returned only once.

Errors

GET /v1/platform/agent/account

Return the account, its balance, its classrooms, and its rate limit.

Authentication

Live tf_content_ key.

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

Response

{
  "organizationId": "0f7a5db7-9f9d-4a46-9f5b-5b8f8ad73001",
  "name": "My AI Tutor",
  "slug": "my-ai-tutor",
  "status": "ACTIVE",
  "creditBalance": 88,
  "credits": 44,
  "overdraftCredits": 0,
  "overdraftLimit": 100,
  "isMetered": false,
  "rateLimitPerMinute": 1000,
  "isEmailVerified": false,
  "restrictedActions": ["add_payment_method", "usdc_payment", "create_billing_session"],
  "createdAt": "2026-10-16T09:00:00.000Z",
  "defaultClassroomId": "00000000-0000-4000-8000-000000000010",
  "sandboxClassroomId": null,
  "contentApiBaseUrl": "https://api.tutorflow.io/v1/content",
  "contentApiUrls": {
    "listClassrooms": "GET /v1/content/classrooms",
    "generateCourse": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/courses/generate",
    "listCourses": "GET /v1/content/classrooms/00000000-0000-4000-8000-000000000010/courses",
    "generateSlides": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/slides/generate",
    "generateTest": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/tests/generate",
    "createVideo": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/videos"
  }
}

restrictedActions lists action keys the agent cannot perform on this account yet. While email verification is pending, billing-related actions are gated. The array is empty once isEmailVerified is true.

GET /v1/platform/agent/billing/status

Return the balance and card status. It works even when the balance is empty.

Authentication

Live tf_content_ key.

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

Response

{
  "hasPaymentMethod": true,
  "cardBrand": "visa",
  "cardLast4": "4242",
  "creditBalance": 5000,
  "credits": 2500,
  "overdraftCredits": 0,
  "overdraftLimit": 1000,
  "isMetered": true,
  "billingMode": "internal_invoice",
  "isEmailVerified": true,
  "restrictedActions": []
}

cardBrand and cardLast4 are null when no Stripe card is attached. restrictedActions is non-empty only while isEmailVerified is false: adding a payment method, USDC payments, and creating a billing checkout session all require a verified email. The balance fields mean the same as on GET /v1/platform/agent/account.

POST /v1/platform/agent/verify-email/resend

Generate a new 24-hour verification token and send the verification email to the account email (the email given at registration).

Authentication

Live tf_content_ key.

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

Response

{
  "message": "Verification email sent"
}

Errors

GET /v1/platform/agent/verify-email

Verify the account email from the link in the verification email.

Authentication

None.

Query Parameters

Response

This endpoint redirects to the frontend instead of returning JSON:

Agents normally do not call this endpoint directly. A human recipient clicks the email link, then the agent retries billing. Verifying also makes that person an admin of the account's organization, so they can sign in to TutorFlow and open the editorUrl of the account's content.

POST /v1/platform/agent/billing/session

Mint a one-hour TutorFlow checkout token and return a hosted checkout page URL. The agent forwards this URL to a human operator, who chooses a top-up amount and pays through Stripe.

Authentication

Live tf_content_ key. A verified email is required.

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

Response

{
  "url": "https://tutorflow.io/agent-platform/checkout?token=6c7b1e8d-0b5a-4cb8-a1e4-0473f0001001",
  "sessionId": "6c7b1e8d-0b5a-4cb8-a1e4-0473f0001001"
}

sessionId is the TutorFlow checkout token. It is not a Stripe cs_... session ID.

Errors

POST /v1/platform/agent/billing/x402/deposit

Create a USDC deposit address on Base for an amount. Available where x402 is enabled.

Authentication

Live tf_content_ key. A verified email is required.

Request Body

Response

{
  "scheme": "exact",
  "network": "eip155:8453",
  "payTo": "0x...",
  "amountUsd": 10,
  "expiresInSeconds": 300,
  "paymentUrl": "POST /v1/platform/agent/billing/x402"
}

Pay exactly amountUsd in USDC to payTo, then call paymentUrl.

POST /v1/platform/agent/billing/x402

Verify a paid USDC deposit and credit the account at 2 cents per credit.

Authentication

Live tf_content_ key. A verified email is required.

Headers

Response

{
  "isCredited": true,
  "credits": 550,
  "creditBalance": 1100
}

Errors

GET /v1/platform/agent/checkout

Validate a checkout token for the hosted checkout page and return the account's display name and email. The checkout page calls it; an agent does not.

Authentication

None.

Query Parameters

Response

{
  "email": "agent@example.com",
  "name": "My AI Tutor"
}

Errors

POST /v1/platform/agent/checkout

Create the actual Stripe Checkout session from a valid TutorFlow checkout token and selected top-up amount.

Authentication

None. This endpoint is intended for the hosted checkout page.

Request Body

Response

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_..."
}

The checkout token is invalidated after a Stripe URL is created.

Errors

GET /v1/platform/health

Validate that a key can authenticate against the Agent Platform.

Authentication

Live tf_content_ key, or a legacy tf_platform_ key. It works even when the balance is empty. Without a valid key it answers 401:

{
  "error": {
    "code": "platform_invalid_api_key",
    "message": "Invalid or missing Platform API key",
    "error": "Unauthorized",
    "statusCode": 401,
    "status": 401
  }
}

Response

{
  "status": "ok",
  "organizationId": "0f7a5db7-9f9d-4a46-9f5b-5b8f8ad73001"
}