Agent Self-Service Onboarding

Overview

The TutorFlow Agent Platform supports agent-driven onboarding. An AI agent can discover the service, create a workspace, obtain an API key, and begin making evaluation requests immediately with $1.00 in free credits. To use the API, the agent must verify its email. No payment method is required while free credits remain. For continued usage after free credits are exhausted, the agent requests a checkout page link and delegates credit purchase to a human operator.

Using Claude or another MCP-compatible agent? Connect via the MCP Integration guide instead. The MCP server exposes all onboarding and evaluation steps as structured tools. No HTTP calls required.

1. Discovery

Agents discover the platform by fetching the public manifest:

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

The response includes the registration endpoint, auth requirements, available services, and documentation URL:

{
  "schema": "https://tutorflow.io/agent-manifest/v1",
  "name": "TutorFlow Agent Platform",
  "description": "AI-powered evaluation, assessment, and tutoring 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"],
  "pricing": { "endpoint": "/v1/platform/pricing-catalog", "currency": "USD" },
  "docs": "https://tutorflow.io/agent-platform/docs",
  "health": "/v1/platform/health"
}

2. Registration

Register by sending a single POST request. No authentication is required.

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-3-5-sonnet via LangChain"
  }'

The response contains the API key (shown only once):

{
  "organizationId": "uuid",
  "apiKey": "tf_platform_...",
  "keyPrefix": "tf_platform_abcd",
  "trialCredits": 100,
  "message": "Store your API key securely. It will not be shown again."
}

The trialCredits field shows the free credits (in cents) granted at signup. New workspaces receive $1.00 (100 cents) in free credits, enough to try the API without registering a payment method.

Rate limit: 5 registrations per IP per hour.

3. Verify Email

After registration, the workspace must verify its email address before making API calls. A verification email is sent automatically at registration. The recipient clicks the link in the email, which calls:

GET https://api.tutorflow.io/v1/platform/agent/verify-email?token=VERIFICATION_TOKEN

If the email did not arrive, the agent can request a new one:

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

Until the email is verified, API calls return a 403 error with code email_verification_required.

4. Billing Setup (after free credits)

After free credits are exhausted, the agent must register a payment method and purchase additional credits. The agent requests a checkout page URL and forwards it to a human operator to choose an amount and complete payment.

While free credits remain, you can skip this step entirely and go straight to Step 5: Start Making API Calls.

4.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": "cs_..."
}

The agent forwards the url to a human (e.g., via Slack, email, or chat). The human opens the TutorFlow-hosted checkout page in a browser, chooses how much to add ($5 minimum, $5,000 maximum), and is then redirected to Stripe to complete payment. No card data passes through the agent or TutorFlow servers.

4.2 Check Billing Status

After the human completes checkout, the agent can verify:

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

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

Alternative: Pay with USDC (x402)

If your agent has a USDC balance on Base network, it can pay per-request without registering a payment method. When free credits are exhausted, API calls return 402 Payment Required with an x402 payload describing how to pay:

{
  "code": "payment_required",
  "x402": {
    "scheme": "exact",
    "network": "eip155:8453",
    "price": "$0.01",
    "payTo": "0x..."
  }
}

The agent sends USDC to the payTo address, waits for on-chain settlement, then retries the request with an X-Payment header. Credits are automatically added to the workspace balance.

x402 support is available when x402.enabled is true in the discovery manifest.

5. Start Making API Calls

With the API key from registration, the agent can immediately call the evaluation endpoint:

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
  }'

6. 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": 93,
  "rateLimitPerMinute": 1000,
  "createdAt": "2026-03-22T00:00:00.000Z"
}

Endpoint Summary