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

curl -s https://api.talonic.com/v1/documents/7f3a1b2c-0000-0000-0000-000000000000/lineage \
  -H "Authorization: Bearer tlnc_your_api_key"

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.

Frequently asked questions

What is document lineage useful for?+
It shows a document's downstream footprint: which pipelines consumed it, which data products ship its values, which registry concepts it contributed, and which cases it belongs to. Use it to trace provenance outward from a single file.
Does a duplicate document show the same lineage as its canonical?+
Pipeline, data-product, and case membership key on the document's own id, so a duplicate shows where its own id was used. The field-registry section keys on the canonical id, so it reflects the concepts the duplicate reads through.
Which resources appear in a document's lineage response?+
Five sections: pipelines that consumed the document, data products built from those pipelines, a field_registry summary of contributed concepts with per-tier counts, and the cases and business_cases the document belongs to. Each entry carries a deep link to its public API surface.

Related

Get Document
Get Document Fields
List Documents