MGPT HTTP API

Base URL

The public gateway and the local backend expose the same routes:

# Public gateway
https://mdl.continualmi.com/api/mgpt

# Local development (backend-api)
http://127.0.0.1:8090/backend-api/mgpt

All examples on this page use the public gateway. The local backend accepts the same bodies under the /backend-api/mgpt prefix.

Authentication

All endpoints require a bearer token issued from the MGPT API console. Keys have the shape cmi_live_<public>.<secret> and are stored hashed in core.api_keys.

Authorization: Bearer cmi_live_<public>.<secret>

The gateway derives the calling user from the key owner. External clients must not send userId or usageForward; the gateway fills those in.

Headers

Generate response

Generate the next assistant turn. Works in three modes — stored universe, inline universe, or standalone single-turn — selected by which optional fields are present.

Required scope: mgpt.responses:create.

Request body

Request modes

• Stored universe — universe + userInput. The normal path. MGPT loads the universe by id, reads the persisted prompt snapshot and output contract, and applies the 64/16 block window before calling the provider.
• Inline universe — universeDoc + userInput. The document is used for the current request only; nothing is persisted. Useful for development.
• Standalone — model + userInput only. Single-turn completion against the provider with no persisted state. Useful for smoke tests.

Response body

{
  "assistantRaw": "string",
  "previewText": "string",
  "promptFingerprint": "sha256:...",
  "nextUniverseTime": "2026-05-06T12:00:00Z",
  "requestLog": { "id": "log_..." },
  "usageSettlement": { /* tokens, billing */ },
  "timingBreakdown": { "totalMs": 612, "providerMs": 540 },
  "diagnostics": {
    "summary":      { /* totals */ },
    "serverStages": [ /* per-stage timings */ ],
    "storage":      { /* universe load info */ },
    "prompt":       { /* window selection */ },
    "provider":     { /* model + provider routing */ }
  }
}

assistantRaw is the canonical handoff. The remaining fields are optional metadata; persist diagnostics stage names verbatim.

Examples

Standalone:

curl https://mdl.continualmi.com/api/mgpt/responses \
  -H "Authorization: Bearer $CONTINUAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mdl-1-lite-frozen",
    "userInput": "Write one sentence about Sintra."
  }'

Stored universe:

curl https://mdl.continualmi.com/api/mgpt/responses \
  -H "Authorization: Bearer $CONTINUAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mdl-1-lite-frozen",
    "universe": "813671db-dd71-4108-a1e7-76e9f3e2bc98",
    "userInput": "Continue from the current state.",
    "requestId": "req_001"
  }'

Inline universe:

curl https://mdl.continualmi.com/api/mgpt/responses \
  -H "Authorization: Bearer $CONTINUAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mdl-1-lite-frozen",
    "userInput": "hello",
    "universeDoc": {
      "conversation": [],
      "runtime": { "conversation": [] }
    }
  }'

Create universe

Create a persistent universe from a server-side stored prompt. The prompt body is loaded from backend-api/prompts/<storedPrompt>.md (or .txt), copied into the universe snapshot, and never returned to the client.

Required scope: mgpt.responses:create.

Request body

Response body

{
  "universe": "813671db-dd71-4108-a1e7-76e9f3e2bc98",
  "userId":   "eaa0d5f0-81e9-4c79-b6f2-cf7db0cb5d63",
  "prompt": {
    "storedPrompt": "emwaver-prompt",
    "stored": true
  }
}

curl https://mdl.continualmi.com/api/mgpt/universes \
  -H "Authorization: Bearer $CONTINUAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storedPrompt": "emwaver-prompt",
    "displayName": "EMWaver Agent"
  }'

Generate image

Generated-scene image endpoint, used by MDL gameplay after a text patch requests a specialScene. MGPT assembles the provider image message: system prompt first, then a single user message with ordered parts (references, then description, then additionalPrompt).

Required scope: mgpt.images:create.

List logs

List recent generation logs, or fetch a single log when identifier is provided. Required scope: mgpt.logs:read.

curl "https://mdl.continualmi.com/api/mgpt/logs?ownerUserId=$USER_ID&kind=text&pageSize=20" \
  -H "Authorization: Bearer $CONTINUAL_API_KEY"

Errors

Errors return JSON with a detail field and an HTTP status.

{ "detail": "Universe not found" }

Scopes