API

Example base URL:

https://api.edu.daven.ai/api/v1/mcp-proxy

OpenAPI: /edu/openapi.yaml

Endpoints

Method	Path	Auth	Description
`GET`	`/health`	none	Health check
`GET`	`/api/session/context`	required	Verified actor, purpose, student, classroom, and activity context
`GET`	`/api/session/roster`	teacher manage session	Safe student display data for the bound classroom
`GET`	`/api/account`	required	Safe shared-school credit summary
`POST`	`/api/quote`	required	Fixed Edu credit quote
`POST`	`/api/text/create`	required	Plain or structured text generation
`POST`	`/api/upload-url`	required	Issue upload URL
`POST`	`/api/media/create`	required	Start generation job
`POST`	`/api/media/get`	required	Poll generation status
`GET`	`/api/catalog`	required	Catalog (`kind`, `query`)

The quote body is { "media_type": "text" | "image" | "video" | "voice" | "music" }. Its estimated_credits matches the fixed credits used by the actual Edu generation route. Other generation body fields vary by model and tool. The upload URL body is { "file_name": string, "mime_type": string }. With the SDK, call daven.uploads.createUrl({ fileName, mimeType }), PUT the bytes to uploadUrl, then pass finalUrl to generation. See Session & proxy for session purposes and actor/student semantics. /api/account returns only billing, billing_ledger, and remaining_credits. It never exposes a Daven user, runtime-key owner, payer ID, or individual balance to an education app.

Idempotent requests

/api/text/create and /api/media/create require an Idempotency-Key.

Generate a new key for each user action. We recommend crypto.randomUUID().
Reuse the key only when retrying that exact request after a network failure.
Reusing a key with another body or user action returns 409.
Retrying a completed request returns its stored response without running AI again.

Managed billing supports text and image generation for schools switched to the Daven ledger. Video, voice, and music return 503 MANAGED_MEDIA_BILLING_UNAVAILABLE until each provider route can suppress its legacy direct charge.

Image generation reserves credits before creating the provider task. /api/media/get settles after it confirms completion and releases the reservation after an explicit provider failure. If your application job restarts, reuse the same Idempotency-Key to resume polling the original task. Image models follow a server allowlist. Classroom default is gpt-image-2.5. If you omit model, Daven picks nano-banana-2, so the app and Hub must send gpt-image-2.5. Apps cannot select a payer or billing mode. Reference images must use public HTTPS URLs.

Response format

Success

{
  "status": "success",
  "data": {},
  "code": "",
  "message": ""
}

Error

{
  "status": "error",
  "error": {
    "code": "AUTH_001",
    "message": "…",
    "detail": "optional"
  }
}

HTTP	Meaning
`200`	Success (also check body `status`)
`400`	Invalid request or `Idempotency-Key` format
`401`	Auth failed
`402`	Insufficient school credits
`404`	Media task is not owned by the current Edu session
`409`	Idempotency conflict or operation already in progress
`422`	Provider confirmed a terminal generation failure
`503`	Billing ledger or recovery temporarily unavailable

Examples

curl -sS "$BASE/api/account" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Edu-Session: $TOKEN"

curl -sS -X POST "$BASE/api/quote" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Edu-Session: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"image"}'

curl -sS -X POST "$BASE/api/media/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Edu-Session: $TOKEN" \
  -H "Idempotency-Key: $OPERATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "media_type":"image",
    "prompt":"A friendly reading passport stamp",
    "model":"gpt-image-2.5",
    "aspect_ratio":"1:1",
    "quality":"quality",
    "reference_image_urls":[]
  }'

curl -sS -X POST "$BASE/api/media/get" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Edu-Session: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"MEDIA_OR_JOB_ID","media_type":"image"}'

curl -sS "$BASE/api/catalog?kind=voices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Edu-Session: $TOKEN"

Get started

MCP

Launch

Endpoints

Idempotent requests

Response format

Success

Error

Examples

​Endpoints

​Idempotent requests

​Response format

​Success

​Error

​Examples

Endpoints

Idempotent requests

Response format

Success

Error

Examples