Lineage API

Document lineage tracking provides Git-like version history for your documents. Track parent-child relationships, compare versions, and visualize document evolution.

Get Document Lineage

Get complete version history for a document lineage.

Path Parameters

document_id

string

required

Document ID

Query Parameters

include_deleted

boolean

default:"false"

Include soft-deleted documents in lineage

Response

lineage_id

string

Unique lineage identifier

total_versions

integer

Total number of documents in lineage

documents

array

Array of documents in chronological order

Document Object

string

Document ID

filename

string

Document filename

content_hash

string

SHA-256 content hash

version_label

string

Human-readable version label

parent_document_id

string

Parent document ID (null for root documents)

similarity_score

number

Similarity to parent (0.0-1.0, null for roots)

created_at

string

ISO 8601 timestamp

file_size_bytes

integer

File size in bytes

is_current

boolean

Whether this is the requested document

{
  "lineage_id": "lineage-001",
  "total_versions": 3,
  "documents": [
    {
      "id": "doc-001",
      "filename": "contract_v1.pdf",
      "content_hash": "sha256-abc123...",
      "version_label": "Initial Draft",
      "parent_document_id": null,
      "similarity_score": null,
      "created_at": "2024-01-15T10:00:00Z",
      "file_size_bytes": 1048576,
      "is_current": false
    },
    {
      "id": "doc-002",
      "filename": "contract_v2.pdf",
      "content_hash": "sha256-def456...",
      "version_label": "Client Review",
      "parent_document_id": "doc-001",
      "similarity_score": 0.87,
      "created_at": "2024-01-20T14:30:00Z",
      "file_size_bytes": 1098752,
      "is_current": false
    },
    {
      "id": "doc-003",
      "filename": "contract_final.pdf",
      "content_hash": "sha256-ghi789...",
      "version_label": "Final - Signed",
      "parent_document_id": "doc-002",
      "similarity_score": 0.94,
      "created_at": "2024-01-25T09:15:00Z",
      "file_size_bytes": 1105920,
      "is_current": true
    }
  ]
}

curl https://api.raptordata.dev/api/documents/doc-003/lineage \
  -H "Authorization: Bearer rd_live_xxx"

Get Lineage Tree

Get lineage as a tree structure showing parent-child relationships.

Path Parameters

document_id

string

required

Document ID

Response

total_versions

integer

Total number of documents in lineage

roots

array

Array of root nodes (documents without parents)

Tree Node Object

string

Document ID

filename

string

Document filename

contentHash

string

SHA-256 content hash

versionLabel

string

Human-readable version label

createdAt

string

ISO 8601 timestamp

children

array

Array of child nodes (recursive structure)

{
  "totalVersions": 5,
  "roots": [
    {
      "id": "doc-001",
      "filename": "contract_v1.pdf",
      "contentHash": "sha256-abc123...",
      "versionLabel": "Initial Draft",
      "createdAt": "2024-01-15T10:00:00Z",
      "children": [
        {
          "id": "doc-002",
          "filename": "contract_v2.pdf",
          "contentHash": "sha256-def456...",
          "versionLabel": "Client Review",
          "createdAt": "2024-01-20T14:30:00Z",
          "children": [
            {
              "id": "doc-003",
              "filename": "contract_final.pdf",
              "contentHash": "sha256-ghi789...",
              "versionLabel": "Final",
              "createdAt": "2024-01-25T09:15:00Z",
              "children": []
            }
          ]
        },
        {
          "id": "doc-004",
          "filename": "contract_v2_alt.pdf",
          "contentHash": "sha256-jkl012...",
          "versionLabel": "Alternative",
          "createdAt": "2024-01-22T11:00:00Z",
          "children": []
        }
      ]
    }
  ]
}

Get Lineage Stats

Get statistics about a document’s lineage.

Path Parameters

document_id

string

required

Document ID

Response

total_versions

integer

Total number of documents in lineage

oldest_version

object

Information about the oldest document in lineage

{
  "total_versions": 5,
  "oldest_version": {
    "id": "doc-001",
    "filename": "contract_v1.pdf",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Find Similar Documents

Find documents that might be versions of the given document (outside current lineage).

Path Parameters

document_id

string

required

Document ID

Query Parameters

min_similarity

number

default:"0.7"

Minimum similarity score (0.0-1.0)

limit

integer

default:"10"

Maximum number of suggestions (1-50)

Response

suggestions

array

Array of similar documents

count

integer

Number of suggestions returned

Link to Parent

Manually link a document to its parent in version lineage.

Path Parameters

document_id

string

required

Child document ID

Request Body

parent_document_id

string

required

Parent document ID

version_label

string

Optional version label

Response

document_id

string

Child document ID

parent_document_id

string

Parent document ID

lineage_id

string

Lineage ID (may be updated)

similarity_score

number

Calculated similarity score

version_label

string

Version label (if set)

{
  "document_id": "doc-003",
  "parent_document_id": "doc-002",
  "lineage_id": "lineage-001",
  "similarity_score": 0.87,
  "version_label": "v2.0"
}

curl -X POST https://api.raptordata.dev/api/documents/doc-003/link-parent \
  -H "Authorization: Bearer rd_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_document_id": "doc-002",
    "version_label": "v2.0"
  }'

Unlink from Lineage

Remove document from its current lineage and create a new lineage.

Path Parameters

document_id

string

required

Document ID to unlink

Response

document_id

string

Document ID

new_lineage_id

string

New lineage ID created

parent_document_id

null

Parent is now null

version_label

null

Version label is cleared

{
  "document_id": "doc-003",
  "new_lineage_id": "lineage-002",
  "parent_document_id": null,
  "version_label": null
}

Get Lineage Changelog

Generate changelog for entire lineage showing version-to-version changes.

Path Parameters

document_id

string

required

Document ID

Response

changelogs

array

Array of version transition objects

total_transitions

integer

Total number of version transitions

Changelog Entry

from_label

string

Starting version label

to_label

string

Ending version label

from_filename

string

Starting version filename

to_filename

string

Ending version filename

similarity_score

number

Similarity between versions (0.0-1.0)

created_at

string

Timestamp of new version

diff

object

Detailed diff information

{
  "changelogs": [
    {
      "from_label": "Initial Draft",
      "to_label": "Client Review",
      "from_filename": "contract_v1.pdf",
      "to_filename": "contract_v2.pdf",
      "similarity_score": 0.87,
      "created_at": "2024-01-20T14:30:00Z",
      "diff": {
        "summary": "Added client feedback sections",
        "added_count": 12,
        "removed_count": 5,
        "modified_count": 8
      }
    },
    {
      "from_label": "Client Review",
      "to_label": "Final",
      "from_filename": "contract_v2.pdf",
      "to_filename": "contract_final.pdf",
      "similarity_score": 0.94,
      "created_at": "2024-01-25T09:15:00Z",
      "diff": {
        "summary": "Minor corrections",
        "added_count": 3,
        "removed_count": 2,
        "modified_count": 4
      }
    }
  ],
  "total_transitions": 2
}

Error Responses

404

Not Found

Document not found or doesn’t belong to user

400

Bad Request

Invalid parameters (e.g., circular lineage detected)

{
  "detail": "Cannot create circular lineage",
  "status_code": 400
}

Get Started

Core Concepts

TypeScript SDK

API Reference

Lineage API

Lineage API

Get Document Lineage

Path Parameters

Query Parameters

Response

Document Object

Get Lineage Tree

Path Parameters

Response

Tree Node Object

Get Lineage Stats

Path Parameters

Response

Find Similar Documents

Path Parameters

Query Parameters

Response

Similar Document Object

Link to Parent

Path Parameters

Request Body

Response

Unlink from Lineage

Path Parameters

Response

Get Lineage Changelog

Path Parameters

Response

Changelog Entry

Error Responses

Get Started

Core Concepts

TypeScript SDK

API Reference

​Lineage API

​Get Document Lineage

​Path Parameters

​Query Parameters

​Response

​Document Object

​Get Lineage Tree

​Path Parameters

​Response

​Tree Node Object

​Get Lineage Stats

​Path Parameters

​Response

​Find Similar Documents

​Path Parameters

​Query Parameters

​Response

​Similar Document Object

​Link to Parent

​Path Parameters

​Request Body

​Response

​Unlink from Lineage

​Path Parameters

​Response

​Get Lineage Changelog

​Path Parameters

​Response

​Changelog Entry

​Error Responses

Lineage API

Get Document Lineage

Path Parameters

Query Parameters

Response

Document Object

Get Lineage Tree

Path Parameters

Response

Tree Node Object

Get Lineage Stats

Path Parameters

Response

Find Similar Documents

Path Parameters

Query Parameters

Response

Similar Document Object

Link to Parent

Path Parameters

Request Body

Response

Unlink from Lineage

Path Parameters

Response

Get Lineage Changelog

Path Parameters

Response

Changelog Entry

Error Responses