Agent Self-Service API

Overview

These endpoints are designed for autonomous agents. Registration and discovery are public. Account and billing status endpoints use the Platform API key from POST /v1/platform/agent/register.

Base URL:

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

GET /v1/platform/pricing-catalog

Return the live pricing catalog used for billing snapshots and agent pre-flight budgeting.

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

Agents should treat the manifest as the source of truth for pricing hints, then call GET /v1/platform/pricing-catalog when exact catalog rows are needed.

POST /v1/platform/agent/register

Create a self-serve platform workspace and return the first API key.

Authentication

None. This endpoint is rate-limited to 5 registrations per IP per hour.

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": "tf_platform_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "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 and creditBalance are internal credit units. They are stored as cents, so 100 means $1.00.

Store apiKey immediately. The raw API key is returned only once.

Errors

GET /v1/platform/agent/account

Return workspace identity, status, credit balance, and rate limit for the authenticated API key.

Authentication

Platform API key.

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

Response

{
  "organizationId": "0f7a5db7-9f9d-4a46-9f5b-5b8f8ad73001",
  "name": "My AI Tutor",
  "slug": "my-ai-tutor",
  "status": "ACTIVE",
  "creditBalance": 88,
  "rateLimitPerMinute": 1000,
  "createdAt": "2026-04-25T00:00:00.000Z"
}

GET /v1/platform/agent/billing/status

Return credit balance and card status. This endpoint skips the billing guard, so agents can call it even after credits are exhausted.

Authentication

Platform API key.

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

Response

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

cardBrand and cardLast4 are null when no Stripe card is attached.

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

Generate a new 24-hour verification token and send the verification email to the workspace email.

Authentication

Platform API key.

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

Response

{
  "message": "Verification email sent"
}

Errors

GET /v1/platform/agent/verify-email

Verify the workspace 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.

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

Platform API key. The billing guard is skipped, but verified email is enforced inside this endpoint.

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=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

GET /v1/platform/agent/checkout

Validate a checkout token for the hosted checkout page and return workspace display information.

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 an API key can authenticate against the platform.

Authentication

Platform API key. This endpoint skips the billing guard, so it still works when credits are exhausted.

Response

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