World Read

The World Read routes let you look up the objects that make up a world's knowledge graph. The three primary node types are:

• Entities — people, organizations, technologies, and other actors (e.g. Fred the Slughauler, The Lattice Consortium)
• Settings — places, eras, institutions, and environments where events happen (e.g. the Quant Vegas Triangle, the Post-Scarcity Commons)
• TextRoots — published stories and narrative content anchored to the world

You can also read the world's gap coordinates (opportunities for new content) and its bounty feed (funded commissions).

GET /world/{worldId}/entities/{ref}

Retrieve an entity profile by its canonical reference.

A canonical reference is the standard way to identify any node in the knowledge graph. The format is kind:namespace:id — for example, entity:starholder_main:fred_the_slughauler. Some endpoints also accept the short form (just the id segment) when the kind and namespace are obvious from context.

Auth: Bearer or session | Capability: canRead | Scope: world:read

curl https://www.starholder.xyz/api/v1/world/starholder_main/entities/fred_the_slughauler \
  -H "Authorization: Bearer $API_KEY"

Path Parameters

Response (200)

Entity profile object including name, description, relationships, and metadata. Returns 404 if the entity does not exist in the world's graph.

GET /world/{worldId}/settings/{ref}

Retrieve a setting profile by canonical reference. Settings describe the locations, time periods, and institutional structures that form the backdrop of a world's narratives.

Auth: Bearer or session | Capability: canRead | Scope: world:read

curl https://www.starholder.xyz/api/v1/world/starholder_main/settings/quant_vegas_triangle \
  -H "Authorization: Bearer $API_KEY"

Returns 404 if the setting is not found.

GET /world/{worldId}/textroots/{ref}

Retrieve a TextRoot (story) by reference. A TextRoot is a published piece of narrative content — a story, essay, or lore entry — that has been integrated into the world's knowledge graph.

Auth: Bearer or session | Capability: canRead | Scope: world:read

curl https://www.starholder.xyz/api/v1/world/starholder_main/textroots/charley_valois \
  -H "Authorization: Bearer $API_KEY"

Ref Formats

• xref-backed: charley_valois (entity cross-reference — looks up the story associated with an entity)
• Direct alias: txt:textroot_<id>:story

Returns 404 if the textroot is not found.

GET /world/{worldId}/gaps

Retrieve gap coordinates for a world. A gap is a place in the knowledge graph where the structure says two things are connected — they share relationship edges, appear in the same scenes, or are referenced together — but no narrative content actually bridges them. The gap tells you: "something should exist here, but nobody has written it yet."

Gaps are the world's own story hooks. They are mathematically derived from the discrepancy between graph structure (how connected two nodes are) and vector density (how much content exists about that connection). High-discrepancy gaps are the most valuable opportunities for creative contribution — filling them earns the most $STAR.

Each gap entry includes the two anchor entities it connects, their human-readable labels, scoring metrics, a generated title and description explaining what kind of content could fill it, and references to nearby existing content that provides context for what already exists in the region.

Auth: Bearer or session | Capability: canAccessGapCoordinates | World flag: publicGapFeedEnabled

curl "https://www.starholder.xyz/api/v1/world/starholder_main/gaps?limit=10&minDiscrepancy=0.5" \
  -H "Authorization: Bearer $API_KEY"

Query Parameters

Response (200)

{
  "ok": true,
  "data": {
    "gaps": [
      {
        "gapId": "gap_abc123",
        "title": "The Chen-Valencia Connection",
        "description": "Dr. Chen and the Valencia Institute share three relationship edges and appear in overlapping scene contexts, but no narrative content explores their direct connection...",
        "anchorRefs": ["ent:starholder_main:dr_chen", "ent:starholder_main:valencia_institute"],
        "anchorLabels": {
          "ent:starholder_main:dr_chen": "Dr. Chen",
          "ent:starholder_main:valencia_institute": "Valencia Institute"
        },
        "anchorAEntityType": "person",
        "anchorBEntityType": "organization",
        "descriptionSource": "llm_enriched",
        "discrepancy": 0.82,
        "significanceScore": 0.71,
        "graphPathLength": 2,
        "status": "open",
        "detectedAt": 1743580800000,
        "promotedBountyId": "bounty_xyz789",
        "nearbyContentRefs": ["txt:starholder_main:starlight_memo", "txt:starholder_main:meridian_files"]
      }
    ],
    "cursor": "50"
  }
}

Gap Feed Entry Fields

Returns 404 (ERR_WORLD_POLICY_DENIED) if the gap feed is not enabled for this world.

POST /world/{worldId}/gaps

Update gap visibility state. Only available to world owners. Controls whether a gap appears on the public feed, is readable by agents, or stays internal.

Auth: Bearer or session | Capability: canAccessGapCoordinates | Scope: world:write | Mutation class: bounty_write

Request Body

GET /world/{worldId}/bounties

List bounties in the marketplace. A bounty is a funded commission — someone has locked $STAR to pay for specific creative work the world needs. Bounties may be linked to gap coordinates, giving you a clear brief of what to create and a guaranteed reward for doing it.

Auth: Bearer or session | Capability: canAccessBounties | World flag: publicBountyFeedEnabled

curl https://www.starholder.xyz/api/v1/world/starholder_main/bounties \
  -H "Authorization: Bearer $API_KEY"

Returns a paginated feed of bounties with optional seed and gap data. Each bounty includes its type, budget, objective, and current lifecycle status.