Universe Data API

The IsounivLib Universe Data API exposes the full worldline cosmology as a single, structured JSON document. It is read-only and requires no authentication. The same payload is served at two canonical paths for flexibility. The sync timestamps are generated dynamically at request time.

Both paths return the identical v1.1 payload with Content-Type: application/json and Access-Control-Allow-Origin: *.

The top-level metadata block identifies the schema and sync state of the export.

The API exposes two clocks. They are generated dynamically at request time - they are not stale constants, so repeated fetches advance them as real time passes.

Progression rule

Worldline time advances deterministically from a canonical epoch. The rule is linear and fully reproducible from the documented constants.

worldline_time = WORLDLINE_EPOCH + (real_now - REAL_EPOCH) * WORLDLINE_RATE

REAL_EPOCH        = "2026-08-26T14:30:00+08:00"
WORLDLINE_EPOCH   = "P0:S0218:A3:2024:06:17:01:22:04.0031"
WORLDLINE_RATE    = 1  (worldline seconds per real second)
timezone          = +08:00
precision         = second + 4-digit sub-frame

// P / S / A coordinates are preserved from the epoch; only the
// YYYY:MM:DD:HH:MM:SS.xxxx portion advances. The .xxxx sub-frame
// encodes the fractional second (0000 - 9999).

Because the endpoint recomputes these values on every request, the served JSON is live at fetch time. The same dynamic values are rendered in the navigator UI on each load.

The payload is nested exactly as the archive is browsed, one level per hierarchy step. Every entity carries a permanent stable ID.

{
  version: "1.1.0",
  schema_version: "1.1",
  source_name: "IsounivLib",
  last_sync_real: "<ISO-8601 with +08:00, recomputed per request>",
  last_sync_world: "<P?:S?:A?:... worldline time, advances with real time>",
  timestamp_spec: "P?:S?:A?:YYYY:MM:DD:HH:MM:SS.xxxx",
  metadata: {
    last_sync_real: "<same as above>",
    last_sync_world: "<same as above>",
    last_sync_worldline: "<same as above>",
    timestamp_spec: "P?:S?:A?:YYYY:MM:DD:HH:MM:SS.xxxx",
    progression: {
      rule: "worldline_time = WORLDLINE_EPOCH + (real_now - REAL_EPOCH) * WORLDLINE_RATE",
      real_epoch: "2026-08-26T14:30:00+08:00",
      worldline_epoch: "P0:S0218:A3:2024:06:17:01:22:04.0031",
      rate: 1.0,
      precision: "second + 4-digit sub-frame",
      timezone: "+08:00"
    }
  },
  hierarchy: ["system", "planet", "region/anomaly", "characters & documents", "timeline events"],
  systems: [
    {
      id: "S0218",
      name: "Std0218",
      civilization: {
        civilization_status: "低活跃度标准系统",
        classification: "Standard-Class System",
        observer_state: "TRACKED"          // enum: see observer_state
      },
      telemetry: {
        heterogeneity: 22,                  // 0-100
        resonance: 30,                      // 0-100
        stability: 88,                     // 0-100
        observer_state: "TRACKED",
        sampled_at: "2026-08-26T14:30:00+08:00",
        sampled_worldline: "P0:S0218:A3:2024:06:17:01:22:04.0031"
      },
      planets: [
        {
          id: "S0218-IV",
          name: "Std0218-IV",
          civilization: { ... },
          telemetry: { ... },
          regions: [
            {
              id: "Hx-Ano-3",
              name: "Hx-Ano#3",
              nameCn: "溶洞古校",
              type: "anomaly",
              civilization: { ... },
              telemetry: { ... },
              characters: [
                {
                  character_id: "CHR-HX-PLAYER",
                  name: "???",
                  nameCn: "？？？",
                  role: "Player / Subject",
                  description: "...",
                  status: "Active / Under observation"
                }
              ],
              documents: [
                {
                  document_id: "DOC-HX-0000",
                  source: "IsounivLib",
                  category: "角色文件",
                  fileTitle: "角色文件《溶洞古校：#0》",
                  worldline: "P0:S0218:A3:2024:06:17:00:00:00.0000",
                  verdict: "...",
                  clearance: "C3",          // C1-C5
                  revision: 1,
                  updated_at: "...",
                  summary: "...",
                  content: "...",
                  language: "zh-CN",
                  tags: ["角色文件", "溶洞古校"],
                  author_ids: ["CHR-HX-ASAGI"],
                  related_character_ids: ["CHR-HX-PLAYER"],
                  related_event_ids: ["EVT-HX-20240617-0001"],
                  content_hash: "a1b2c3d4",
                  supersedes_document_id: null
                }
              ],
              timeline: [
                {
                  event_id: "EVT-HX-20240617-0001",
                  worldline: "...",
                  label: "...",
                  type: "document",          // document | event | anomaly
                  related_document_ids: ["DOC-HX-0000"]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  intervention_logs: [
    {
      log_id: "INT-HX-0042",
      worldline: "...",
      real_time: "...",
      actor: "SUSTAINER-07",
      level: "WARN",
      action: "SURFACE_ROLL_CALL",
      message: "...",
      result: "APPROVED",
      related_document_ids: ["DOC-HX-0002"]
    }
  ]
}

Document record attributes

intervention_logs record

Every system, planet, and region carries a live telemetry snapshot. The three metrics are normalized 0-100 values; observer_state is a strict enum.

Example telemetry block

{
  "heterogeneity": 78,
  "resonance": 64,
  "stability": 41,
  "observer_state": "CONTAINED",
  "sampled_at": "2026-08-26T14:30:00+08:00",
  "sampled_worldline": "P0:S0218:A3:2024:06:17:01:22:04.0031"
}

Strict enum values used across the schema. Use these exact strings.

observer_state

clearance (C1 - C5)

operation state

timeline event type

Sustained worldline interventions are executed through a structured, validated pipeline. Every operation passes through explicit states before it touches the worldline fabric.

Guarantees & controls

Standardized operation states

Submit request (202 Accepted)

POST /api/v1/operations
Content-Type: application/json
Idempotency-Key: key_8f3a91

{
  "action": "SURFACE_ROLL_CALL",
  "worldline": "P0:S0218:A3:2024:06:17:00:41:22.0002",
  "actor": "SUSTAINER-07",
  "level": "WARN",
  "expected_revision": 1,
  "requires_approval": true
}

// -> 202 Accepted
{
  "schema_version": "1.1",
  "request_id": "op_1724680000_4821",
  "idempotency_key": "key_8f3a91",
  "status": "accepted",
  "state": "approval_required",
  "possible_states": ["draft","validated","approval_required","queued",
    "executing","applied","rejected","failed","cancelled","rolled_back"]
}

The custom.interference.directive command is retained for free-form worldline directives. It is always wrapped in a validated, structured schema before submission - raw directives are never executed.

{
  "action": "custom.interference.directive",
  "worldline": "P0:S0218:A3:2024:06:17:00:41:22.0002",
  "actor": "SUSTAINER-07",
  "level": "WARN",
  "expected_revision": 1,
  "payload": {
    "directive": "cross-reference roll-call register against guild records",
    "scope": "Hx-Ano#3",
    "interference": "LOW"
  }
}

Any action beginning with custom. passes validation and is routed through the same operation pipeline as standard commands.

This section is a design proposal describing how IsounivLib could be exposed as a Model Context Protocol (MCP) server to bridge directly with Poke (Shirone) / Lab Connect. It is documentation only - no MCP endpoint is currently served.

Proposed tool surface

tools:
  - universe.get_systems
  - universe.get_region
  - universe.get_document
  - universe.get_timeline
  - universe.get_telemetry
  - universe.validate_operation     -> POST /api/v1/operations/validate
  - universe.submit_operation      -> POST /api/v1/operations  (202, approval_required)
  - universe.list_interventions

resources:
  - universe://systems
  - universe://regions/{id}
  - universe://documents/{document_id}

Fetch the full hierarchy:

const data = await fetch("https://isounivlib.cyanide.poke.site/api/universe_data.json").then((r) => r.json());

for (const system of data.systems) {
  console.log(system.name, system.civilization.classification);
  for (const planet of system.planets) {
    for (const region of planet.regions) {
      console.log("  " + (region.nameCn || region.name),
        "observer:", region.telemetry.observer_state,
        "stability:", region.telemetry.stability);
      for (const doc of region.documents) {
        console.log("    " + doc.document_id, doc.title, "@", doc.worldline);
      }
    }
  }
}

Build a single worldline timeline across all worlds:

const data = await fetch("https://isounivlib.cyanide.poke.site/api/universe_data.json").then((r) => r.json());

const timeline = data.systems
  .flatMap((s) => s.planets)
  .flatMap((p) => p.regions)
  .flatMap((r) => r.timeline)
  .sort((a, b) => a.worldline.localeCompare(b.worldline));

console.table(timeline);

Validate and submit an operation:

const proposal = {
  action: "SURFACE_ROLL_CALL",
  worldline: "P0:S0218:A3:2024:06:17:00:41:22.0002",
  actor: "SUSTAINER-07",
  level: "WARN",
  expected_revision: 1
};

const validated = await fetch(
  "https://isounivlib.cyanide.poke.site/api/v1/operations/validate",
  { method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify(proposal) }
).then((r) => r.json());

if (validated.valid) {
  const submitted = await fetch(
    "https://isounivlib.cyanide.poke.site/api/v1/operations",
    { method: "POST",
      headers: { "Content-Type": "application/json", "Idempotency-Key": "key_8f3a91" },
      body: JSON.stringify({ ...proposal, requires_approval: true }) }
  );
  // 202 Accepted
  console.log(submitted.status, await submitted.json());
}

Try the real validation endpoint against the live server. Edit the proposal and run it.