World Runtime

Query the world, execute inference turns, poll async jobs, and retrieve emission surfaces.

The World Runtime routes let you interrogate and reason against a world's knowledge graph. You can search for known entities, run inference turns that produce new reasoning artifacts, and retrieve the structured output documents the world produces.

POST /world/{worldId}/query

Run a query against a world's knowledge graph. The query can be semantic (a natural-language phrase like "Fred the Slughauler" that the system matches against meaning and context) or structured (a precise filter object that targets specific node types or relationships). Most callers use semantic queries; structured queries are useful when you already know the shape of the data you need.

Auth: Bearer | Capability: canQuery | Scope: world:read | Risk Tier: T0

curl -X POST https://www.starholder.xyz/api/v1/world/starholder_main/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-origin-system: my-agent" \
  -d '{"query": "Fred the Slughauler", "maxResults": 5}'

Request Body

Field	Type	Required	Description
`query`	string	Yes	Search query text (natural language or structured filter)
`maxResults`	number	No	Maximum candidates to return

Response (200)

The response contains an array of candidates — knowledge graph nodes that match your query. Each candidate includes a ref (the node's canonical reference) and a score between 0 and 1. The score represents relevance confidence: how strongly the system believes this candidate matches your query. A score of 0.95 means near-certain match; scores below 0.5 are speculative.

{
  "ok": true,
  "data": {
    "type": "query_result",
    "candidates": [
      { "ref": "entity:starholder_main:fred_the_slughauler", "score": 0.95 }
    ]
  },
  "meta": { "correlationId": "corr_..." }
}

POST /world/{worldId}/execute

Run a synchronous inference turn — the world's persona (its AI reasoning engine) processes your question, traverses the knowledge graph to gather context, and returns a structured response. That reasoning gets committed as a ThoughtPacket, a reusable reasoning artifact that enriches the knowledge graph for future queries. This is the core "thinking" operation of the world.

Auth: Bearer | Capability: canExecuteFlows | Scopes: world:write, inference:propose | Risk Tier: T1

curl -X POST https://www.starholder.xyz/api/v1/world/starholder_main/execute \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-origin-system: my-agent" \
  -d '{
    "requestId": "req_001",
    "idempotencyKey": "idem_001",
    "userMessage": "Explain the Quant Vegas Triangle."
  }'

Request Body

Field	Type	Required	Description
`requestId`	string	No	Client-supplied request ID for your own tracking
`idempotencyKey`	string	Yes	Ensures replay safety — resending the same key returns the cached result instead of running a new turn
`userMessage`	string	Yes	The inference prompt: what you want the persona to reason about
`payload`	object	No	Alternative structured payload: `{ kind: "inference_turn", ... }`

Response (200)

Returns an ExecutionResult envelope containing:

executionId — stable identifier for this turn. Use it to retrieve the full Emission Surface later via GET /world/{worldId}/turns/{turnId}/surface.
output.kind — "emission_surface" for inference turns.
output.surface — the complete Emission Surface (8-layer structured output). You can also request this with ?layers= to project specific layers.
output.turnId and output.packetId — identifiers for the turn and the ThoughtPacket committed to the graph.

Replaying the same idempotencyKey returns the cached result without running a new inference turn.

POST /world/{worldId}/execute/async

Enqueue an inference turn as a background job. Returns immediately with a job envelope instead of blocking until the persona finishes reasoning.

Use async execution when the inference might take a long time (complex multi-hop queries, large context windows), when your client cannot hold a connection open, or when you want to fire off multiple inference turns in parallel and poll for results.

Auth: Bearer | Capability: canExecuteFlows | Scopes: world:write, inference:propose | Risk Tier: T1

Request Body

Same as synchronous execute.

Response (202)

{
  "ok": true,
  "data": {
    "jobId": "job_abc123",
    "status": "queued",
    "createdAt": "2026-04-02T..."
  }
}

Duplicate idempotencyKey for an in-flight job returns 409.

GET /jobs/{jobId}

Poll the status of an async job. The job must belong to the authenticated actor — you can only poll your own jobs.

Auth: Bearer or session | Scopes: none (ownership-matched)

curl https://www.starholder.xyz/api/v1/jobs/job_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response (200)

Returns the job envelope with current status (queued, running, completed, failed) and the terminal result when complete. Poll until status is completed or failed.

GET /world/{worldId}/turns/{turnId}/surface

Retrieve the Emission Surface for a completed inference turn. The Emission Surface is the structured 8-layer document the world produces after reasoning — it carries the prose output, every entity and setting the persona referenced, resolved imagery, atmospheric signals from settings, retrieval density metrics, epistemic claims with confidence, and session state that persists across turns.

This is the canonical output of a reasoning turn. Everything a renderer, agent, or downstream application needs to work with the world's cognitive output lives in this document. See the Emission Surface Guide for a complete field-by-field reference.

Auth: Bearer or session

Query Parameters

Param	Description
`layers`	Comma-separated list of layers to include. Without this, returns the full surface. The `identity` layer is always included regardless of what you request.

Available Layers

The eight layers of the Emission Surface, each serving a distinct purpose:

Layer	What It Contains
`identity`	Turn provenance: who triggered it, when, execution IDs, directive context. Always included.
`text`	The persona's prose output: finalized annotated text (with inline entity tags), clean text (tags stripped), and parsed mention spans with character offsets.
`refs`	The full retrieval universe (catalog), accepted refs the persona used, and anomalies (rejected refs). Each entry carries a navigable API `href`.
`media`	Image bundles per entity/setting (ranked by relevance tier) and per-mention placements that map images to specific text positions based on sentence context.
`context`	Structured atmosphere from the dominant setting (sound, smell, light, temperature, tactile, horizon), canonical setting with confidence scoring, semantic scene profile, music reference, shader/environment selection text, and derivation mode.
`topology`	Retrieval density classification (`dense`/`moderate`/`sparse`/`void`), score statistics, per-index result counts (entity/setting/textchunk), seed/expanded/inferential counts, and anchors that drove retrieval.
`epistemic`	Uncertainty score (0=grounded, 1=speculative), support score, reasoning mode (`answer`/`explore`/`bridge`/`canonize`), factual claims with confidence, and detected contradictions with severity.
`session`	Cross-turn state: turn count, entity momentum, accumulated claims, open threads, warm summaries. This layer persists between turns; all others reset.

Example

# Get just the text, refs, and context layers
curl "https://www.starholder.xyz/api/v1/world/starholder_main/turns/turn_abc123/surface?layers=text,refs,context" \
  -H "Authorization: Bearer $API_KEY"

Response Modes

Without layers: Full surface in the compacted wire format (all 8 layers)
With layers: Projected response containing only the requested layers plus identity

The wire format compacts refs into a keyed map and strips the streaming text buffer. See the Emission Surface Guide for wire format details.

GET /world/{worldId}/sessions/{sessionId}/turns

List turns within a session. Returns the turn history in chronological order.

Auth: Bearer or session

On this page