Auth: required. Send an ivy_ API key (Authorization: Bearer ivy_… or X-Ivy-Api-Key), a Clerk session JWT (Authorization: Bearer …) or the Clerk __session cookie (browser sessions). See Authentication.

Records which outputs of other jobs fed a job you can write to. Each source names a producer job, one of its outputs (producer_output_id) and the input slot it filled.

Every producer job must be one you can read, and every producer_output_id must be an output of its producer job; otherwise the request returns 403 and nothing is recorded. A source without producer_output_id is skipped, and a request where every source lacks one returns 202 with a warning. A project viewer can read lineage but not record it; recording returns 404 for them, the same as for a job that does not exist.

With a project-scoped API key, the job and every producer job must be in one of the key's projects.

Request

Path parameters

jobIdstring (uuid)

UUID of the consuming job.

Request body

sourcesobject[]

Example

{
  "sources": [
    {
      "producer_job_id": "00000000-0000-0000-0000-000000000001",
      "producer_output_id": "00000000-0000-0000-0000-000000000002",
      "input_slot": "protein_structure"
    }
  ]
}

Responses

`201` Created

Lineage recorded

Response shape:

successenum (true)

insertedinteger

Rows recorded

`202` Accepted

Accepted, but nothing was recorded; warning says why (no source carried producer_output_id, or lineage storage is unavailable)

Response shape:

acceptedenum (true)

warningstring

`400` Bad Request

The job id is empty; the body has no sources; or a source is missing producer_job_id or input_slot, or has a producer_output_id that is null or empty

Response shape: object

`401` Unauthorized

Authentication required

Response shape: object

`403` Forbidden

A producer job is not one you can read (or is outside your API key's project scope), or an output is not an output of its producer job. Nothing is recorded.

Response shape: object

`404` Not Found

The job does not exist, you cannot write to it, it is outside your API key's project scope, or the id is not a job UUID. All of these return the same body.

Response shape: object

`429` Too Many Requests

Rate limit exceeded

Response shape: object

`500` Internal Server Error

Recording lineage failed

Response shape: object

curl -X POST 'https://ivybiosciences.com/api/v1/jobs/{jobId}/lineage' \
  -H "Authorization: Bearer $IVY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "sources": [
    {
      "producer_job_id": "00000000-0000-0000-0000-000000000001",
      "producer_output_id": "00000000-0000-0000-0000-000000000002",
      "input_slot": "protein_structure"
    }
  ]
}'

POST /v1/jobs/{jobId}/lineage