Ingest one lineage event

POST one OpenLineage RunEvent, JobEvent, or DatasetEvent and receive a durable receipt.

`POST /api/v1/lineage`

Accepts one event conforming to the OpenLineage object model and the OpenLineage 2-0-2 JSON schema. Embrasure preserves the original request bytes, then validates and projects the event asynchronously.

Authentication and idempotency

Send Authorization: Bearer <token>. The token needs write scope and the caller needs the editor workspace role or higher. See authentication.

Idempotency-Key is optional and accepts 1 to 600 characters. Reuse a key only when retrying the exact same request bytes; using it with different bytes returns 409 lineage_idempotency_conflict. Without a key, Embrasure deduplicates byte-identical requests by SHA-256 digest.

Query parameters

Name	Type	Required	Description
`workspace_id`	string	With session JWTs or other unscoped tokens	Target workspace. A workspace-scoped PAT can omit it; an explicit value must match the token's workspace.
`connector_id`	string	No	Connector scope used to resolve dataset identities.
`provider_key`	string, 1–500 characters	No	Stable producer identity. Its connector binding cannot be changed after first use.

Requests with neither a workspace_id parameter nor a workspace-scoped PAT fail with openlineage_workspace_required. The PAT needs write scope and its user needs editor or administrator access in the workspace.

Headers

Name	Required	Description
`Authorization`	Yes	Bearer token with write scope.
`Content-Type`	Yes	`application/json`.
`Idempotency-Key`	No	Retry key, 1–600 characters.

The uncompressed request body must be no larger than 8 MiB. Content-Encoding values other than identity are rejected.

Request body

The body is one of the standard OpenLineage event types:

Type	Required event-specific fields	Use
`RunEvent`	`run`, `job`; optional `eventType`, `inputs`, `outputs`	Runtime job-state and data-flow observations.
`JobEvent`	`job`; optional `inputs`, `outputs`; no `run`	Design-time job metadata and declared lineage.
`DatasetEvent`	`dataset`; no `job` or `run`	Design-time dataset metadata.

Every event requires eventTime (RFC 3339 timestamp), producer (URI), and schemaURL (URI). Jobs and datasets require a non-empty namespace and name. A run requires a UUID runId. eventType, when supplied, is START, RUNNING, COMPLETE, ABORT, FAIL, or OTHER. Standard and custom OpenLineage facets are accepted.

Complete `RunEvent` example

{
  "eventType": "COMPLETE",
  "eventTime": "2026-08-05T18:42:12Z",
  "producer": "https://github.com/acme/orders-pipeline",
  "schemaURL": "https://openlineage.io/spec/2-0-2/OpenLineage.json",
  "run": {
    "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "job": {
    "namespace": "airflow-production",
    "name": "orders.refresh_orders"
  },
  "inputs": [
    {
      "namespace": "snowflake://acme.us-east-1",
      "name": "RAW.PUBLIC.ORDERS"
    }
  ],
  "outputs": [
    {
      "namespace": "snowflake://acme.us-east-1",
      "name": "ANALYTICS.PUBLIC.ORDERS"
    }
  ]
}

curl --request POST \
  --url "https://api.embrasure.ai/api/v1/lineage?workspace_id=workspace-1&connector_id=connector-1&provider_key=airflow-production" \
  --header "Authorization: Bearer $EMBRASURE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: run-0190-complete" \
  --data-binary @openlineage-event.json

`202` response

{
  "delivery_id": "c5ecf66d-1ca4-4e86-ae60-51c9108490cf",
  "state": "accepted",
  "duplicate": false,
  "item_count": 1,
  "invalid_item_count": 0
}

Field	Type	Meaning
`delivery_id`	string	Durable delivery identifier.
`state`	`accepted`	Transport acceptance; semantic validation and graph projection are still asynchronous.
`duplicate`	boolean	The idempotency key or payload digest matched an existing delivery.
`item_count`	integer	Always `1` for this route.
`invalid_item_count`	integer	Always `0` in a successful single-event receipt.

Errors

All failures use the shared error envelope.

Status	Codes	When
`400`	`openlineage_body_required`, `openlineage_invalid_json`, `openlineage_invalid_event`, `invalid_content_length`	Missing body, malformed JSON, duplicate JSON keys, non-object body, or invalid length header.
`401`	`unauthorized`	Missing or invalid bearer token.
`403`	`insufficient_scope`, `insufficient_workspace_role`, `workspace_token_mismatch`	Token or caller cannot write to the workspace.
`409`	`lineage_idempotency_conflict`, `lineage_provider_scope_conflict`	A retry key has different bytes, or the provider/connector binding conflicts.
`413`	`openlineage_body_too_large`	Body exceeds 8 MiB.
`415`	`openlineage_content_encoding_unsupported`	Request body is compressed.
`422`	`openlineage_workspace_required`, `validation_error`	Workspace cannot be inferred or a query/header constraint fails.

The 202 LineageDeliveryReceipt confirms durable acceptance, not completed graph projection. Read ingest lineage for identity-resolution behavior.

Ingest one lineage event

On this page