Spec Document, Graph & Share

Compose the customer-facing Spec document, derive the read-only workflow graph, and manage the public share token for a Spec.

These endpoints surface the customer-facing views of a Spec. The document endpoint composes the Spec specification (field definitions, rules, gates, samples, and delivery) on every request so it never drifts from live config. The graph endpoint derives the read-only Workflow Graph (a DAG) from the Spec rail and validation gates. The share endpoints manage a public token that exposes the composed document to people without an API key.

The composed document and the graph are config only. They describe how the Spec is set up: field definitions, rules, gates, and sample filenames. They never include cell values or document ids. This is what makes the share link safe to hand to a customer: the unguessable token is the authorization, and the surface behind it carries no extracted data.

Creating a share token when one already exists rotates it, which revokes the old link. Reading the share endpoint returns the current token, or null when there is no active link. Revoking removes the link entirely.

Response

The document is the composed specification. The graph is { nodes, edges } describing stages plus the implicit branches (a gate fail routes to a review outcome, the registry has an on_unmapped fallback). The share endpoints return a { token } object.

{
  "nodes": [
    { "id": "source", "label": "Source" },
    { "id": "extraction", "label": "Extraction" },
    { "id": "validation_totals", "label": "Totals must reconcile" },
    { "id": "review", "label": "Review queue" },
    { "id": "data_product", "label": "Data Product" }
  ],
  "edges": [
    { "from": "source", "to": "extraction" },
    { "from": "extraction", "to": "validation_totals" },
    { "from": "validation_totals", "to": "data_product" },
    { "from": "validation_totals", "to": "review", "branch": "fail" }
  ]
}

{
  "token": "spec_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
}

GET share returns { "token": null } when no link is active. DELETE share returns { "revoked": true }.

Errors