Delivery links

Read and correct which GitHub pull requests deliver an idea or initiative. Request ideas:read or initiatives:read to read, and ideas:write or initiatives:write to change links for that kind of record. A PR claims completion only through a Zentrik: closes trailer.

3 endpoints

GET

List delivery links

GET /external/v1/delivery-links

List the pull requests linked to one idea or initiative (record), or the ideas and initiatives linked to one pull request (url, or repository and number). Each link has status (linked counts as delivery; suggested, rejected and withdrawn are kept for their history), intent (closes when the PR claims it completes the record), source (trailer, branch or manual) and declaredBy, where the PR names the record today. Links to an initiative's promoted ideas are listed on those ideas. A pull request lookup also returns declaredReferences and only the record kinds the key can read.

Requirements

API scopes required:

ideas:read

initiatives:read

Request

Parameters

Name	Type	Description
record	string	IDEA-n or INITIATIVE-n. Give this or a pull request. Needs ideas:read or initiatives:read for that kind.
url	url	Pull request URL. Give this, or number, instead of record.
number	integer	Pull request number.
repository	string	owner/repository, needed with number when several tracked repositories have it.
includeInactive	boolean	true adds rejected and withdrawn links. Read them before re-linking a pair.

Responses

200

Success

record or pullRequest, and items.

400

Invalid request

Unsupported field, a record that is not IDEA-n or INITIATIVE-n, both or neither of url and number, or a number several tracked repositories share.

403

Missing scope

The key lacks ideas:write for an idea or initiatives:write for an initiative.

404

Not found

The record is not in this workspace, or the pull request has not been synced from a repository the workspace tracks.

Example Response

200 OK

json

{
  "record": {
    "type": "idea",
    "publicId": "IDEA-42",
    "name": "Selective import",
    "status": "Approved"
  },
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "record": {
        "type": "idea",
        "publicId": "IDEA-42",
        "name": "Selective import",
        "status": "Approved"
      },
      "pullRequest": {
        "repository": "example/app",
        "number": 42,
        "title": "Import only the selected sources",
        "state": "merged",
        "url": "https://github.com/example/app/pull/42",
        "mergedAt": "2026-09-10T10:00:00.000Z"
      },
      "status": "linked",
      "intent": "relates",
      "source": "manual",
      "declaredBy": null,
      "reviewedAt": "2026-09-10T10:00:00.000Z"
    }
  ]
}

POST

Link a PR to a record

POST /external/v1/delivery-links

Link a pull request to an idea or initiative it works on, as related work, the same as linking it in the app. Repeating the call returns changed:false. It never claims the PR completes the record: only a Zentrik: closes IDEA-n line in the PR body does that, and note returns the line to add. Linking a pair someone rejected restores it.

Requirements

API scopes required:

ideas:write

initiatives:write

Request

Request body (application/json)

recordstring

Required

IDEA-n or INITIATIVE-n.

pullRequest.urlurl

https://github.com/owner/repository/pull/number. Give this or pullRequest.number.

pullRequest.numberinteger

Pull request number. Give this or pullRequest.url.

pullRequest.repositorystring

owner/repository. Needed with number when more than one tracked repository has that number.

Responses

200

Success

changed says whether anything was saved; item is the link as it now stands.

400

Invalid request

Unsupported field, a record that is not IDEA-n or INITIATIVE-n, both or neither of url and number, or a number several tracked repositories share.

403

Missing scope

The key lacks ideas:write for an idea or initiatives:write for an initiative.

404

Not found

The record is not in this workspace, or the pull request has not been synced from a repository the workspace tracks.

Example Request

POST

/external/v1/delivery-links

json

{
  "record": "IDEA-42",
  "pullRequest": { "url": "https://github.com/example/app/pull/42" }
}

Example Response

200 OK

json

{
  "changed": true,
  "item": {
    "id": "33333333-3333-4333-8333-333333333333",
    "record": {
      "type": "idea",
      "publicId": "IDEA-42",
      "name": "Selective import",
      "status": "Approved"
    },
    "pullRequest": {
      "repository": "example/app",
      "number": 42,
      "title": "Import only the selected sources",
      "state": "merged",
      "url": "https://github.com/example/app/pull/42",
      "mergedAt": "2026-09-10T10:00:00.000Z"
    },
    "status": "linked",
    "intent": "relates",
    "source": "manual",
    "declaredBy": null,
    "reviewedAt": "2026-09-10T10:00:00.000Z"
  },
  "note": "Linked as related work. To claim this PR completes IDEA-42, add \"Zentrik: closes IDEA-42\" to its body; Zentrik reads completion only from the PR."
}

POST

Reject a delivery link

POST /external/v1/delivery-links/unlink

Reject a wrong link between a pull request and an idea or initiative. The rejection is remembered, so the pair is not linked again from the same PR text. When the PR still names the record, followUp says which line to change. A link whose trailer the PR has already dropped is withdrawn instead (status withdrawn), so it returns if the reference comes back. Does not change the record's status or a recorded shipment.

Requirements

API scopes required:

ideas:write

initiatives:write

Request

Request body (application/json)

recordstring

Required

IDEA-n or INITIATIVE-n.

pullRequest.urlurl

https://github.com/owner/repository/pull/number. Give this or pullRequest.number.

pullRequest.numberinteger

Pull request number. Give this or pullRequest.url.

pullRequest.repositorystring

owner/repository. Needed with number when more than one tracked repository has that number.

Responses

200

Success

changed says whether anything was saved; item is the link as it now stands.

400

Invalid request

Unsupported field, a record that is not IDEA-n or INITIATIVE-n, both or neither of url and number, or a number several tracked repositories share.

403

Missing scope

The key lacks ideas:write for an idea or initiatives:write for an initiative.

404

Not found

The record is not in this workspace, or the pull request has not been synced from a repository the workspace tracks.

Example Request

POST

/external/v1/delivery-links/unlink

json

{
  "record": "IDEA-42",
  "pullRequest": { "repository": "example/app", "number": 42 }
}

Example Response

200 OK

json

{
  "changed": true,
  "item": {
    "id": "33333333-3333-4333-8333-333333333333",
    "record": {
      "type": "idea",
      "publicId": "IDEA-42",
      "name": "Selective import",
      "status": "Approved"
    },
    "pullRequest": {
      "repository": "example/app",
      "number": 42,
      "title": "Import only the selected sources",
      "state": "merged",
      "url": "https://github.com/example/app/pull/42",
      "mergedAt": "2026-09-10T10:00:00.000Z"
    },
    "status": "rejected",
    "intent": "relates",
    "source": "trailer",
    "declaredBy": {
      "in": "trailer",
      "intent": "relates"
    },
    "reviewedAt": "2026-09-10T10:00:00.000Z"
  },
  "followUp": "The PR body still has a Zentrik: line naming IDEA-42. The link stays rejected, but remove IDEA-42 from that line so the PR and Zentrik agree."
}