API Reference

Base URL

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

Authentication

External endpoints require a valid Platform API key passed via the Authorization header. Internal management endpoints are authenticated through TutorFlow admin auth. See Authentication for details.

Endpoints Overview

Evaluations (API Key required)

Method	Endpoint	Description
`POST`	`/evaluations`	Create an evaluation request
`GET`	`/evaluations/:id`	Get evaluation result
`GET`	`/evaluations/:id/files/:field/:index`	Download evaluation files
`GET`	`/evaluations`	List evaluation requests. Supports `learnerId` filter

Learners (API Key required)

Method	Endpoint	Description
`GET`	`/learners`	List learners with aggregate evaluation stats
`GET`	`/learners/:learnerId`	Get learner profile with per-concept mastery summaries

Courses (API Key required)

Method	Endpoint	Description
`POST`	`/courses`	Create a course generation request
`GET`	`/courses/:id`	Get course by ID
`GET`	`/courses`	List course requests
`POST`	`/courses/:id/edit-token`	Generate an edit token for a course
`GET`	`/courses/public/:shareToken`	Get public course by share token
`GET`	`/courses/public/:shareToken/full`	Get full public course with lessons
`GET`	`/courses/public/:shareToken/lessons/:sequence`	Get public lesson by sequence
`GET`	`/courses/edit/:editToken`	Get course by edit token
`GET`	`/courses/edit/:editToken/full`	Get full course with lessons
`GET`	`/courses/edit/:editToken/lessons/:sequence`	Get lesson by edit token
`PATCH`	`/courses/edit/:editToken/lessons/:sequence`	Update lesson by edit token
`PATCH`	`/courses/edit/:editToken`	Update course by edit token
`POST`	`/courses/edit/:editToken/lessons`	Add a new lesson to a course
`POST`	`/courses/edit/:editToken/infer-type`	Infer best lesson type from title/context

Tests (API Key required)

Method	Endpoint	Description
`POST`	`/tests`	Create a test generation request
`GET`	`/tests/:id`	Get test by ID
`GET`	`/tests`	List test requests
`POST`	`/tests/:id/edit-token`	Generate an edit token for a test
`GET`	`/tests/:id/submissions`	List submissions for a test
`GET`	`/tests/public/:shareToken`	Get public test by share token
`GET`	`/tests/public/:shareToken/full`	Get full public test with items and answers
`GET`	`/tests/public/:shareToken/items/:sequence`	Get public item by sequence
`GET`	`/tests/public/:shareToken/take`	Get test for taking (no answers)
`POST`	`/tests/public/:shareToken/submissions`	Start a test submission
`PATCH`	`/tests/submissions/:submissionToken`	Save or finalize submission answers
`GET`	`/tests/submissions/:submissionToken/result`	Get a finalized submission result
`GET`	`/tests/edit/:editToken`	Get test by edit token
`GET`	`/tests/edit/:editToken/full`	Get full test with items by edit token
`GET`	`/tests/edit/:editToken/items/:sequence`	Get item by edit token
`PATCH`	`/tests/edit/:editToken`	Update test by edit token
`PATCH`	`/tests/edit/:editToken/items/:sequence`	Update item by edit token

Agent Self-Service

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

LTI 1.3 Integration

Method	Endpoint	Auth	Description
`POST`	`/lti/registrations`	API Key	Create an LTI registration
`GET`	`/lti/registrations`	API Key	List LTI registrations
`GET`	`/lti/registrations/:id`	API Key	Get an LTI registration
`PUT`	`/lti/registrations/:id`	API Key	Update an LTI registration
`DELETE`	`/lti/registrations/:id`	API Key	Delete an LTI registration
`GET`	`/lti/login`	None	OIDC login initiation (called by LMS)
`POST`	`/lti/launch`	None	Launch callback (called by LMS)
`POST`	`/lti/deep-linking/response`	None	Deep linking response callback
`GET`	`/lti/.well-known/jwks.json`	None	Public JWKS endpoint

Health

Method	Endpoint	Auth	Description
`GET`	`/health`	API Key	Health check (validates API key)

MCP

Agents can also connect via the Model Context Protocol instead of calling REST endpoints directly.

Transport	URL
Streamable HTTP	`https://mcp.tutorflow.io/api/mcp`

Dashboard (Admin Auth required)

Method	Endpoint	Description
`GET`	`/dashboard/workspaces`	List accessible workspaces
`GET`	`/dashboard/workspaces/:id`	Get workspace detail
`PUT`	`/dashboard/workspaces/:id`	Update workspace (name, slug, auto-reload)
`GET`	`/dashboard/workspaces/:id/members`	List members
`GET`	`/dashboard/workspaces/:id/member-invites`	List member invites
`POST`	`/dashboard/workspaces/:id/member-invites`	Invite a member
`POST`	`/dashboard/workspaces/:id/member-invites/:inviteId/resend`	Resend invite
`DELETE`	`/dashboard/workspaces/:id/member-invites/:inviteId`	Cancel invite
`GET`	`/dashboard/workspaces/:id/api-keys`	List API keys
`POST`	`/dashboard/workspaces/:id/api-keys`	Create an API key
`POST`	`/dashboard/workspaces/:id/api-keys/:keyId/rotate`	Rotate an API key
`POST`	`/dashboard/workspaces/:id/api-keys/:keyId/revoke`	Revoke an API key
`GET`	`/dashboard/workspaces/:id/pricing-catalog`	List pricing catalog
`GET`	`/dashboard/workspaces/:id/usage/summary`	Usage summary
`GET`	`/dashboard/workspaces/:id/usage/details`	Usage details
`GET`	`/dashboard/workspaces/:id/billing/invoices`	List invoices
`GET`	`/dashboard/workspaces/:id/billing/invoices/:invoiceId`	Get invoice
`GET`	`/dashboard/workspaces/:id/billing/payment-method`	Get payment method
`POST`	`/dashboard/workspaces/:id/billing/payment-method-session`	Create payment method session
`POST`	`/dashboard/workspaces/:id/billing/purchase-credits`	Purchase credits ($5–$5,000)
`GET`	`/dashboard/workspaces/:id/evaluations`	List evaluations
`GET`	`/dashboard/workspaces/:id/evaluations/:evaluationId`	Get evaluation
`GET`	`/dashboard/workspaces/:id/courses`	List courses
`GET`	`/dashboard/workspaces/:id/courses/:courseId`	Get course
`GET`	`/dashboard/workspaces/:id/webhooks`	List webhooks
`POST`	`/dashboard/workspaces/:id/webhooks`	Create a webhook
`DELETE`	`/dashboard/workspaces/:id/webhooks/:webhookId`	Delete a webhook
`GET`	`/dashboard/workspaces/:id/lti/registrations`	List LTI registrations
`POST`	`/dashboard/workspaces/:id/lti/registrations`	Create LTI registration
`DELETE`	`/dashboard/workspaces/:id/lti/registrations/:regId`	Delete LTI registration
`GET`	`/dashboard/workspaces/:id/lti/launches`	List recent LTI launches
`POST`	`/dashboard/workspaces/:id/lti/keys/rotate`	Rotate LTI signing key

Internal Management

Method	Endpoint	Description
`POST`	`/workspaces`	Create a workspace
`GET`	`/workspaces`	List workspaces
`GET`	`/workspaces/:id`	Get workspace details
`PATCH`	`/workspaces/:id`	Update workspace
`POST`	`/workspaces/:id/credits`	Add credits to workspace
`POST`	`/workspaces/:id/suspend`	Suspend a workspace
`POST`	`/workspaces/:id/activate`	Reactivate a workspace
`POST`	`/workspaces/:id/link`	Link workspace to TutorFlow organization
`POST`	`/workspaces/from-organization`	Create workspace from existing organization
`POST`	`/api-keys`	Create an API key
`GET`	`/api-keys`	List API keys
`POST`	`/api-keys/:id/revoke`	Revoke an API key
`POST`	`/api-keys/:id/rotate`	Rotate an API key
`POST`	`/webhooks`	Create a webhook endpoint
`GET`	`/webhooks`	List webhook endpoints
`DELETE`	`/webhooks/:id`	Delete a webhook endpoint
`GET`	`/usage`	Usage summary
`GET`	`/usage/details`	Usage details
`GET`	`/admin/stats`	Platform-wide statistics
`GET`	`/admin/stats/daily`	Daily usage breakdown
`GET`	`/admin/stats/organizations`	Usage ranked by organization
`POST`	`/billing/invoices`	Create billing invoice draft
`POST`	`/billing/webhooks/stripe`	Stripe webhook handler

Response Format

All responses return JSON. Successful responses include the resource directly:

{
  "id": "uuid",
  "status": "COMPLETED",
  "evaluationType": "open_ended",
  "score": 8,
  "feedbackSummary": "Strong answer..."
}

External Platform API key error responses follow this format:

{
  "error": {
    "code": "platform_invalid_request",
    "message": "Validation failed",
    "status": 400
  }
}