Ingest a SQLMesh project export

POST a rendered SQLMesh project export as a partial or complete declared-lineage acquisition.

`POST /v1/lineage/sqlmesh/project`

Authentication and idempotency

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

Send Idempotency-Key or source_event_key, each 1 to 500 characters. If both are present, they must match. complete acquisitions require a stable project_id and a caller-supplied key. Use a new key for every acquisition and reuse it only for identical content.

Request body

Field	Type	Required	Description
`workspace_id`	string	Yes	Target workspace.
`connector_id`	string	Yes	Connector scope for relation resolution.
`project`	object	Yes	`embrasure.sqlmesh-project@v1` export, including its SQLMesh environment.
`project_id`	string	For `complete`	Stable identifier for this SQLMesh project.
`completeness`	`partial` or `complete`	No	Defaults to `partial`. A complete snapshot is scoped by connector, project, and SQLMesh environment.
`source_event_key`	string, 1–500 characters	No	Body alternative to `Idempotency-Key`.

Complete request example

{
  "workspace_id": "workspace-1",
  "connector_id": "connector-1",
  "project_id": "analytics-sqlmesh",
  "completeness": "complete",
  "source_event_key": "sqlmesh-build-842",
  "project": {
    "schema": "embrasure.sqlmesh-project@v1",
    "sqlmesh_version": "0.190.0",
    "project": {
      "name": "analytics"
    },
    "environment": "prod",
    "dialect": "snowflake",
    "generated_at": "2026-08-05T18:42:12Z",
    "external_models": [
      {
        "name": "raw.orders",
        "fqn": "RAW.PUBLIC.ORDERS",
        "columns": {
          "ORDER_ID": "NUMBER"
        }
      }
    ],
    "models": [
      {
        "name": "analytics.orders",
        "fqn": "ANALYTICS.PUBLIC.ORDERS",
        "physical_table": "ANALYTICS.PUBLIC.ORDERS__ABC123",
        "kind": "FULL",
        "language": "sql",
        "depends_on": ["RAW.PUBLIC.ORDERS"],
        "rendered_sql": "select ORDER_ID from RAW.PUBLIC.ORDERS",
        "path": "models/orders.sql"
      }
    ]
  }
}

curl --request POST https://api.embrasure.ai/v1/lineage/sqlmesh/project \
  --header "Authorization: Bearer $EMBRASURE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: sqlmesh-build-842" \
  --data-binary @embrasure-sqlmesh-request.json

`202` response

{
  "ok": true,
  "delivery_id": "58c74445-3271-463c-b5ff-6b13cc24362a",
  "status": "accepted",
  "accepted": true,
  "duplicate": false,
  "item_count": 1,
  "invalid_item_count": 0,
  "dispatch_requested": true,
  "models": 1,
  "nodes": 2,
  "dependencies": 1,
  "column_maps": 1,
  "observations": 1,
  "completeness": "complete",
  "scope_key": "connector:connector-1:sqlmesh-project:analytics-sqlmesh:prod"
}

The receipt confirms durable acceptance. A complete prod export never retracts dev lineage. Embrasure rejects a complete snapshot when export-shape errors would make retraction lossy.

Errors

All failures use the shared error envelope.

Status	Codes	When
`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`	Keys conflict, content changed for a reused key, or provider scope cannot be bound.
`422`	`validation_error`, `lineage_snapshot_invalid`	Request/export fields are invalid, or a complete snapshot lacks exact scope/key or is not lossless.

Column-lineage outcomes

Situation	Result
SQL model with rendered SQL	Parsed only when every read matches a declared dependency.
Python model	Table dependencies remain; columns report `non_sql_model`.
No rendered SQL	Table dependencies remain; columns report `rendered_sql_unavailable`.
Rendered SQL reads an undeclared relation	No mapping is guessed; columns report `rendered_sql_reads_outside_declared_dependencies`.
Embedded dependency	No relation is emitted; model metadata reports `embedded_dependency_has_no_relation`.
External model or seed	Accepted as a dependency target without producing its own declared observation.
SQL parser limitation	The parser's `unresolved_reason` is preserved.

See pipelines and applications for runtime-event and exporter setup.