Mentrast Logo
Mentrast
Developer Reference · v2LIVE

API.
REFERENCE.

REST API. ASYNC QUEUE. WEBHOOK DELIVERY. ALL ENDPOINTS GATED BY ISSUED API KEY. FULL STRUCTURED JSON ON EVERY RESPONSE.

Quick Start
curriculum-generate.sh
bash
# 1. Send a curriculum generation request
curl -X POST https://api.mentrast.com/v2/curriculum/generate \
  -H "x-api-key: mk_live_7f91a3bc9204ee1d" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id":    "usr_7f91a3bc",
    "topic":      "Advanced Node.js Microservices",
    "timeframe":  "6 months",
    "complexity": "advanced",
    "options": {
      "diagnostic_first": true,
      "webhook_url": "https://your-app.com/hooks/mentrast"
    }
  }'

# → Returns immediately:
# { "id": "cur_8f92j10x", "job_id": "job_4aa19z02", "status": "queued" }

# 2. Webhook fires ~8s later with full JSON curriculum
# Or poll: GET /v2/curriculum/cur_8f92j10x/status
All Endpoints · v2api.mentrast.com
POSTCore
/v2/curriculum/generate

Generate a full structured curriculum. Returns job_id for async polling or webhook.

GETQueue
/v2/curriculum/:id/status

Poll generation progress. Returns current gate stage and completion percentage.

GETResult
/v2/curriculum/:id

Retrieve completed curriculum — full module/lesson JSON with estimates and objectives.

PATCHEdit
/v2/curriculum/:id/lesson/:lid

Rewrite any lesson in-place with a natural-language instruction string.

GETExplain
/v2/explain

Explain any concept at configurable depth, audience level, and format.

POSTAuth
/v2/keys

Issue a new API key with quota, rate limit, and role configuration.

GETMetering
/v2/keys/:id/usage

Retrieve usage, quota consumed, cache hit rate, and cost breakdown per key.

POSTEvents
/v2/webhooks

Register a webhook endpoint to receive curriculum.completed events on generation finish.

Authentication

Every endpoint requires a valid issued key via the x-api-key header. Keys are scoped per organization, carry quota limits, and can be rotated or revoked without touching your integration.

Header:
x-api-key: mk_live_your_key_here
curriculum:generateTrigger curriculum generation jobs
curriculum:readRetrieve generated curricula and status
curriculum:editRewrite lessons via Edit & Explain API
keys:manageIssue, rotate, and revoke API keys
webhooks:writeRegister and manage webhook endpoints
Node.js SDK
generate-curriculum.ts
typescript
import MentrastClient from "@mentrast/sdk";

const client = new MentrastClient({
  apiKey: process.env.MENTRAST_API_KEY,
});

// Generate a full curriculum — async, non-blocking
const { id, job_id } = await client.curriculum.generate({
  topic:      "Advanced Node.js Microservices",
  timeframe:  "6 months",
  complexity: "advanced",
  options: {
    diagnosticFirst: true,
    webhookUrl: "https://your-app.com/hooks/mentrast",
  },
});

// Poll for completion
const result = await client.curriculum.waitForCompletion(id);
console.log(`Generated ${result.meta.total_lessons} lessons across ${result.meta.total_modules} modules`);

// Edit any lesson with natural language
await client.curriculum.editLesson(id, result.modules[0].lessons[0].index, {
  instruction: "Make this lesson more Socratic with embedded questions",
});
Webhook Payload · curriculum.completed
webhook-payload.json
json
{
  "event":          "curriculum.completed",
  "curriculum_id":  "cur_8f92j10x",
  "job_id":         "job_4aa19z02",
  "timestamp":      "2026-05-08T21:04:33Z",
  "status":         "active",
  "generation_ms":  7840,
  "cache_hit":      false,
  "meta": {
    "total_modules":  10,
    "total_lessons":  47,
    "estimated_hours": 186
  },
  "retrieve": "GET https://api.mentrast.com/v2/curriculum/cur_8f92j10x"
}
Error Codes
400Bad Request

Invalid parameters or malformed JSON

401Unauthorized

Missing or invalid x-api-key header

403Forbidden

Key lacks required scope for endpoint

404Not Found

Curriculum or resource ID doesn't exist

429Rate Limited

Quota exhausted — check Retry-After header

500Server Error

Include x-request-id when contacting support

Request API KeyEngine Modules