Skip to content
pkgPlease Docs

Pre-flight a proposed dependency set

POST
/api/v1/policy/{registry_type}/plan
curl --request POST \
  --url https://api.pkgplease.com/api/v1/policy/example/plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "proposed": { "additionalProperty": "example" }, "baseline": { "additionalProperty": "example" } }'

Backs the MCP plan_dependencies tool. Diffs proposed against the optional baseline and evaluates only the added and changed entries through the shared evaluator (evaluatePackage), the same code path as check and the registry install. Unchanged entries, and entries in the baseline but absent from proposed (removals), are counted in unchanged and never evaluated; with no baseline every entry is added. A changed entry is never steered: a steer on a changed entry is reported as allow, with no steer field. Blocks and approvals still apply to changed entries. Read-only — it never creates an approval — and records exactly one audit event (mcp.plan_dependencies) per call. Unscored entries are queued for scoring at their resolved version. Each entry is rendered by token type exactly as check renders it.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
registry_type
required
string

One of the org's configured registry types (npm is the one in active use).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
proposed
required

Package name to version spec — what package.json will contain. At most 100 entries.

object
<= 100 properties
key
additional properties
string
baseline

Package name to version spec — what package.json contains now.

object
key
additional properties
string
Examplegenerated
{
  "proposed": {
    "additionalProperty": "example"
  },
  "baseline": {
    "additionalProperty": "example"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

One decision per added or changed entry, plus the overall rollup

Media typeapplication/json
object
decision

The most severe entry decision (block > needs-approval > warn > steer > endorse > allow); allow when there are no entries. Entries in not_evaluated do not contribute.

string
Allowed values: allow endorse steer warn needs-approval block
entries
Array<object>
object
name
string
spec
string
change
string
Allowed values: added changed
decision
string
Allowed values: allow endorse steer warn needs-approval block
reason
string
block_class

Present only on a block.

string
Allowed values: security policy
pack

The pack id that produced the decision

string
remediation

As in check.

object
type
string
Allowed values: version cohort-peer
version
string
package
string
entry_id

Session-token responses only.

string
nullable
override_eligibility

Session-token responses only, as in check.

object
resolved_version

The version the spec resolves to

string
scored

False when no fresh score exists yet; scoring has been queued.

boolean
askable
boolean
steer

Present only on a steer — the org's endorsed cohort peer.

object
package
string
version
string
reason
string
not_evaluated

Entries the evaluator could not evaluate. They never appear in entries.

Array<object>
object
name
string
spec
string
reason
string
Allowed values: non-registry-spec no-satisfying-version package-not-found upstream-unavailable
unchanged

Entries identical to the baseline

integer
Example
{
  "decision": "allow",
  "entries": [
    {
      "change": "added",
      "decision": "allow",
      "block_class": "security",
      "remediation": {
        "type": "version"
      }
    }
  ],
  "not_evaluated": [
    {
      "reason": "non-registry-spec"
    }
  ]
}

400

Section titled “400”

Missing or non-object proposed

Media typeapplication/json
object
error
required
string
Examplegenerated
{
  "error": "example"
}