CONTINIUMDEVELOPER API
Developer API
Production endpoints for third-party integrations: create an app, mint API keys, upsert end-users, run simulations, create snapshots, submit check-ins, and send feedback.
AUTH OVERVIEW
// App management (create app / mint keys)
Authorization: Bearer <Continium user token>
// Engine endpoints (simulate, snapshot, check-in, feedback)
X-API-Key: ck_<keyId>.<secret>
Apps + keys are created by a signed-in Continium user. Runtime engine calls use an API key.
BASE URL
BASE
https://<your-domain>/api
// All developer endpoints are under:
/api/dev/*If you host Continium behind a custom domain, use that domain.
ERRORS
// Common response shapes
{ "error": "Missing API key" }
{ "error": "Unauthorized" }
// Rate limit
HTTP 429
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Please slow down.",
"retry_after_seconds": 12
}Use Retry-After when present.
1) APPS + API KEYS
CREATE APP
POST /api/dev/apps
{
"name": "My Integration",
"description": "Optional"
}
// Response (api_key returned ONCE)
{
"app": { "app_id": "...", "name": "..." },
"api_key": "ck_<keyId>.<secret>"
}Requires a signed-in Continium user (Bearer auth handled by the dashboard session).
KEY LIFECYCLE
GET /api/dev/apps
POST /api/dev/apps/:appId/keys
GET /api/dev/apps/:appId/keys
POST /api/dev/apps/:appId/keys/:keyId/revokeKeys are never shown again after creation. Rotate keys by minting a new one and revoking the old one.
2) END-USER PROFILES
UPSERT USER
POST /api/dev/users/upsert
X-API-Key: ck_<keyId>.<secret>
{
"external_user_id": "user_123",
"profile": {
"age": 28,
"location": "US-NYC",
"income": "120k",
"profession": "Software Engineer",
"skills": { "technical": 0.7, "communication": 0.55 }
}
}
// Response
{
"app_id": "...",
"external_user_id": "user_123",
"user_id": "app:<appId>:user_123"
}You control external_user_id. Continium creates a stable internal user_id namespaced to your app.
3) RUN SIMULATION
SIMULATE
POST /api/dev/engine/simulate
X-API-Key: ck_<keyId>.<secret>
{
"external_user_id": "user_123",
"num_simulations": 100,
"horizon": 60,
"difficulty": "normal",
"difficulty_params": {
"rent_multiplier": 1.1
},
"policy_overrides": {
"save_rate": 0.2
}
}Structured input only (no Gemini parsing). Use difficulty_params for numeric overrides.
RESULT
// Response includes results + meta
{
"simulation_id": "...",
"results": { "scenarios": { "median": { /* ... */ } } },
"meta": { "num_simulations": 100, "horizon": 60 }
}Persist simulation_id if you want to snapshot or check-in later.
4) SNAPSHOTS
CREATE SNAPSHOT
POST /api/dev/tie/snapshot
X-API-Key: ck_<keyId>.<secret>
{
"simulation_id": "...",
"timeline_type": "median",
"branch": "baseline"
}Snapshots give you a navigable artifact (timeline arrays + final state).
5) CHECK-INS + FEEDBACK
CHECK-IN
POST /api/dev/check-in
X-API-Key: ck_<keyId>.<secret>
{
"snapshot_id": "...",
"month": 12,
"observed": {
"income": 95000,
"happiness": 73,
"health_score": 78,
"sleep_avg_h": 7.2,
"social_score": 0.62,
"avg_skill_level": 0.58,
"net_worth": 135000
}
}A check-in calibrates the posterior (TIE) and can update per-user residual/world models.
FEEDBACK
POST /api/dev/feedback
X-API-Key: ck_<keyId>.<secret>
{
"external_user_id": "user_123",
"state_before": { /* ... */ },
"action_taken": { /* ... */ },
"state_after": { /* ... */ },
"rating": 5
}Feedback stores a training sample (and may feed world-model learning).
6) WORLD MODEL (OPTIONAL)
STATUS
GET /api/dev/tie/world_model/status?external_user_id=user_123
X-API-Key: ck_<keyId>.<secret>Returns whether a learned per-user world model is active.
TRAIN
POST /api/dev/tie/world_model/train
X-API-Key: ck_<keyId>.<secret>
{
"external_user_id": "user_123",
"model_version": "v1"
}Training is optional; most integrations can ignore this unless you want personalization to converge faster.
NEXT
Implementation notes
These routes are served by the Next.js app under /api/dev and proxy to the simulation engine. For app creation + key management, use the dashboard (signed-in). For engine usage, store the API key securely and call from your backend.