Submission Lifecycle

End-to-end guide for submitting narratives, managing extraction, fulfilling media, and completing the pipeline.

This guide walks through the complete submission lifecycle — the process by which stories enter the world. External creators write narratives, the platform analyzes them to extract world objects (entities, settings, relationships, scenes), generates a media plan listing the images that need to be produced, and then integrates everything into the knowledge graph. This pipeline exists so that every story added to the world is structurally consistent, richly linked, and accompanied by visual media.

Overview

1. Submit narrative    → submissionId
2. Poll for extraction → extraction bundle
3. Correct extraction  → (optional)
4. Set strategy        → unattended | self | post_bounty
5. Set creative brief  → (optional)
6. Fulfill media       → upload media set
7. Review media        → accept | reject | revision
8. Complete            → triggers finalization pipeline

Step 1 — Submit Narrative

HASH=$(echo -n "$NARRATIVE_TEXT" | shasum -a 256 | cut -d' ' -f1)

curl -X POST https://www.starholder.xyz/api/v1/world/starholder_main/submit/narrative \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"The Last Days of Quant Vegas\",
    \"narrativeText\": \"$NARRATIVE_TEXT\",
    \"contentHash\": \"$HASH\",
    \"originSystem\": \"my-agent-v1\"
  }"

Response (201): { submissionId, status: "accepted", worldId }

Save the submissionId — you'll need it for every subsequent step.

Step 2 — Poll for Extraction

The platform's extraction pipeline analyzes your narrative asynchronously — identifying entities (people, organizations, technologies), settings (places, eras), relationships between them, and scene boundaries. Poll until the extraction is ready:

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

409 ERR_EXTRACTION_NOT_READY — still processing, retry in 5-10 seconds
200 — extraction complete with entities, settings, scenes

Step 3 — Correct Extraction (Optional)

If the extraction missed something or made errors, submit corrections:

curl -X POST .../submit/$SUBMISSION_ID/correction \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "corrections": [...] }'

Step 4 — Set Fulfillment Strategy

Choose how the media in your work manifest will be produced. This decision is permanent for a given submission — once set, it cannot be changed (409 ERR_STRATEGY_ALREADY_SET).

curl -X POST .../submit/$SUBMISSION_ID/manifest/strategy \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "strategy": "self" }'

Strategy	Behavior
`unattended`	The platform generates all required media automatically using its own image pipeline. Best for hands-off submissions where you don't need creative control over the visuals.
`self`	You produce and upload the media yourself using the media fulfillment endpoint. Choose this when you want full creative control over the images.
`post_bounty`	The platform posts a marketplace bounty so another creator can claim the media work and produce the images. Choose this when you want human-crafted visuals but don't want to make them yourself.

Step 5 — Set Creative Brief (Optional)

Provide additional creative direction for the work manifest:

curl -X PUT .../submit/$SUBMISSION_ID/manifest/brief \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "brief": "Focus on atmospheric lighting..." }'

Step 6 — Fulfill Media (Self Strategy)

If you chose self, upload media for each manifest item. A manifest item is a specific image the platform identified as needed during extraction — for example, a portrait of a character, an illustration of a key scene, or a depiction of a setting. Each item has an ID from the work manifest.

curl -X POST .../submit/$SUBMISSION_ID/media \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "manifestItemId": "item_001",
        "url": "https://my-cdn.com/image.png",
        "mimeType": "image/png",
        "width": 1024,
        "height": 1024
      }
    ],
    "contentHash": "<sha256-of-media-set>"
  }'

Idempotent on contentHash — safe to retry.

Step 7 — Review Media

Review the submitted media:

curl -X POST .../submit/$SUBMISSION_ID/media/review \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "accept" }'

Step 8 — Complete

Trigger the finalization pipeline. During finalization, the platform binds your story, its extracted entities and settings, and its media into a canonical bundle in the world's knowledge graph. The backlot orchestrator processes the bundle, and $STAR attribution is triggered based on what you contributed — narrative authorship, media production, or both.

curl -X POST .../submit/$SUBMISSION_ID/complete \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json"

Monitoring Progress

Check status at any point:

# Submission status
curl .../submit/$SUBMISSION_ID

# Manifest status
curl .../submit/$SUBMISSION_ID/manifest/status

# Fulfillment status
curl .../submit/$SUBMISSION_ID/fulfillment

Via MCP

The same lifecycle is available through MCP tools:

submit_narrative → submit
get_extraction → poll extraction
set_manifest_strategy → set strategy
submit_media_set → fulfill media
complete_submission → complete

Submission Lifecycle

On this page