Spec Document, Graph & Share

Compose the customer-facing Spec document, derive the read-only workflow graph DAG, and create, rotate, or revoke the public share token for a Spec via API.

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 the live configuration. 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 configuration 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.

curl -s https://api.talonic.com/v1/schemas/a1b2c3d4-e5f6-7890-abcd-ef1234567890/graph \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

The document is the composed specification. The graph is { nodes, edges }: each node carries an id, a kind (source, registry, extraction, validation, resolution, review, delivery, …), a display label, an optional sub line, and a config object tying it back to the rail (railId, phaseType, and for a validation node the validationStageId plus the targetPhases it checks). Edges carry kind: "sequence" for the main flow and kind: "outcome" for implicit branches, such as a blocking gate's fail path into a review node. A Spec with no rail set derives the graph from the default stage sequence. The share endpoints return a { token } object.

{
  "nodes": [
    { "id": "n0-source", "kind": "source", "label": "Source", "config": { "railId": "s-source" } },
    {
      "id": "n1-extraction",
      "kind": "extraction",
      "label": "Extraction",
      "config": { "phaseType": "extraction", "railId": "s-schema" }
    },
    {
      "id": "n2-validation",
      "kind": "validation",
      "label": "Totals must reconcile",
      "config": {
        "phaseType": "validation",
        "railId": "s-valid",
        "validationStageId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "targetPhases": ["extraction"]
      }
    },
    {
      "id": "n3-review",
      "kind": "review",
      "label": "Review",
      "sub": "human queue",
      "config": { "railId": "s-valid", "gateId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890" }
    }
  ],
  "edges": [
    { "id": "e0", "from": "n0-source", "to": "n1-extraction", "kind": "sequence" },
    { "id": "e1", "from": "n1-extraction", "to": "n2-validation", "kind": "sequence" },
    {
      "id": "e2",
      "from": "n2-validation",
      "to": "n3-review",
      "kind": "outcome",
      "outcome": "fail",
      "label": "fail → review"
    }
  ]
}

{
  "token": "G1MxmRrMyTQBIKToCtncO7riARpT8v5S"
}

The share token is an unguessable 32-character base64url string. GET share returns { "token": null } when no link is active. DELETE share returns { "revoked": true }.

Errors