Skip to main content

Get Document Lineage

Trace a document's downstream footprint: the pipelines that consumed it, data products built from them, registry concepts it contributed, and its cases.

The Get Document Lineage endpoint, GET /v1/documents/{id}/lineage, returns a document's downstream footprint across the Talonic platform. This is the "used in" view: where a document ended up after ingestion, rather than what it contains. It answers questions like "which pipelines consumed this file?", "which data products ship its values?", and "which cases does it belong to?".

The response groups the footprint into sections: pipelines (the engine runs that included the document), data_products (datasets built from those pipelines), field_registry (the canonical concepts the document contributed, with per-tier counts and a sample), cases, and business_cases. Each entry carries a deep link to the corresponding public surface, so you can follow lineage outward without constructing URLs yourself.

Pipeline, data-product, and case membership key on the document's own id; the field-registry section keys on the effective (canonical) id, so a linked duplicate reflects the concepts it reads through. This is the document passport — new platform surfaces that reference documents are added here over time.
GET/v1/documents/{id}/lineage

Path parameters

id*stringThe document UUID.

Response

Response fields

document_idstringThe document UUID.
pipelines[]objectPipelines that consumed the document (id, name, status, document_status, schema, links.self).
data_products[]objectData products built from those pipelines (id, name, status, links.self).
field_registry.totalintegerDistinct canonical concepts the document contributed.
field_registry.by_tierobject[]Per-tier concept counts (tier 1 = Canonical, 2 = Established, 3 = Provisional).
field_registry.sampleobject[]A capped sample of contributed concepts.
cases[]objectCases the document belongs to (id, case_key, status, links.self).
business_cases[]objectBusiness cases the document belongs to.

curl

Response

{
  "document_id": "7f3a1b2c-0000-0000-0000-000000000000",
  "pipelines": [
    { "id": "c3d4e5f6-...", "name": "Delivery Notes", "status": "completed",
      "document_status": "completed", "schema_id": "b2c3d4e5-...",
      "schema_name": "Delivery Note", "links": { "self": "/v1/pipelines/c3d4e5f6-..." } }
  ],
  "data_products": [
    { "id": "d4e5f6a7-...", "name": "Q2 Deliveries", "status": "active",
      "links": { "self": "/v1/data-products/d4e5f6a7-..." } }
  ],
  "field_registry": {
    "total": 18,
    "by_tier": [ { "tier": 1, "count": 12 }, { "tier": 2, "count": 6 } ],
    "sample": [ { "canonical_name": "invoice_total", "display_name": "Invoice Total", "tier": 1 } ],
    "links": { "fields": "/v1/fields?document_id=7f3a1b2c-..." }
  },
  "cases": [],
  "business_cases": []
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
404document_not_foundNo document with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Get Document
Get Document Fields
List Documents