> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Start dependency update runs on demand and poll their status through the REST API without enabling a schedule.

# Dependency Updates

Use the Dependency Updates API to start a run for a connected repository and
poll its status. An on-demand run uses the same update generation, package risk
policy, and publication safeguards as scheduled
[Secure Dependency Updates](https://www.superagent.sh/docs/security-workers/secure-dependency-updates).

All requests require an organization API key sent as a bearer token in the
`Authorization` header, as described in the [REST API](https://www.superagent.sh/docs/api).
Repositories and runs are scoped to the API key's organization.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/repositories/{repositoryId}/dependency-updates` | Start an asynchronous dependency update run |
| `GET` | `/dependency-updates/{runId}` | Retrieve an organization-scoped run and its status |

`repositoryId` is the positive integer ID of a connected GitHub repository. `runId` is
the UUID returned when a run is accepted.

## Start a run

`POST /api/v1/repositories/{repositoryId}/dependency-updates` starts one run.
The repository must belong to the API key's organization and have an active
Superagent Security GitHub App installation. A live private run costs **5 credits**
when it starts, even if it fails or finds no updates. Public repositories and
`dryRun: true` cost no credits.

You can start a run while the repository schedule is **Off**. Starting a run
does not enable or change the schedule.

### Request

The optional JSON body accepts `scope` and `dryRun`:

| Field | Type | Description |
| --- | --- | --- |
| `scope` | string | Optional: `vulnerabilities`, `versions`, or `all`. Defaults to the repository's saved dependency update scope |
| `dryRun` | boolean | Set `true` to resolve updates without writing GitHub branches or pull requests. Defaults to `false` |

- `vulnerabilities` targets known vulnerable dependencies.
- `versions` checks direct dependencies for available versions.
- `all` checks vulnerability remediation and regular version updates in one run.

Use `{"scope":"versions","dryRun":true}` to test ordinary updates separately
from `{"scope":"vulnerabilities","dryRun":true}`. Neither request changes the
saved scope or publishes pull requests.

An explicit scope applies to this run without changing the repository's saved
scope. Omit the body, or send `{}`, to use the saved scope. Requests reject
unsupported JSON fields.

```bash
curl https://superagent.sh/api/v1/repositories/1095278383/dependency-updates \
  -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"vulnerabilities"}'
```

### Response

`202 Accepted`

```json
{
  "data": {
    "id": "7b6e70c5-8cd2-4f9e-95dd-4a24e3c8a019",
    "object": "dependency_update_run",
    "repository_id": 1095278383,
    "scope": "vulnerabilities",
    "mode": "manual",
    "status": "queued",
    "dry_run": false,
    "summary": null,
    "proposal_count": 0,
    "skipped_count": 0,
    "published_count": 0,
    "error_message": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-10-01T12:00:00.000Z",
    "updated_at": "2026-10-01T12:00:00.000Z"
  }
}
```

Accepted means the run has been queued, not that a pull request has been
published. If a run is already `queued` or `in_progress` for the repository,
the request returns `409 conflict` rather than starting another run.
An unavailable or inactive repository or GitHub App installation returns
`404 not_found`. A live private run that would exceed the free-plan credit
allocation returns `402` before it is queued. The worker rechecks capacity
when the run begins; intervening usage can cause an accepted run to fail.

## Retrieve run status

`GET /api/v1/dependency-updates/{runId}` returns `200 OK` with the run under
`data`, using the same object shape as the start response.

```bash
curl https://superagent.sh/api/v1/dependency-updates/7b6e70c5-8cd2-4f9e-95dd-4a24e3c8a019 \
  -H "Authorization: Bearer sk_live_..."
```

### Run fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Run UUID |
| `object` | string | Always `dependency_update_run` |
| `repository_id` | number | Connected GitHub repository ID |
| `scope` | string | Effective scope: `vulnerabilities`, `versions`, or `all` |
| `mode` | string | `manual` for on demand runs; `daily`, `weekly`, or `monthly` for scheduled runs |
| `status` | string | `queued`, `in_progress`, `completed`, or `failed` |
| `dry_run` | boolean | Whether publication is disabled for this run |
| `summary` | object or null | Versioned, validated run evidence: alert source and target count, Dependabot job counts, candidate count, published and refreshed pull requests, withheld reasons, and error codes; independent of diagnostic logs |
| `proposal_count` | number | Update candidates generated by Dependabot for runs with summaries; use `summary` to distinguish missing evidence from zero |
| `skipped_count` | number | Candidates withheld from publication; reasons are in `summary.withheld` |
| `published_count` | number | Pull requests opened or refreshed during a completed live run; always `0` in dry-runs |
| `error_message` | string or null | Run failure information, or `null` when no error is recorded |
| `started_at` | string or null | Time execution started, or `null` before execution |
| `completed_at` | string or null | Time execution reached a terminal status, or `null` while active |
| `created_at` | string | Time the run was created |
| `updated_at` | string | Time the run was last updated |

Check `summary`, not status alone. `summary.complete` is `false` when a
Dependabot job failed, jobs were truncated, or candidates could not be
collected; missing evidence is not zero updates. `summary.alerts.source` is
`dependabot` when open Dependabot alerts were read, `osv` when Superagent fell
back to OSV advisories, and `none` for version-only runs. `summary.jobs` counts
one Dependabot job per ecosystem and manifest directory.

`summary.withheld` lists why candidates were not published:

| Reason | Meaning |
| --- | --- |
| `flagged` | The supply-chain scan confirmed a finding in the new package version |
| `scanner-incomplete` | The scan could not reach a conclusive result |
| `scanner-failed` | The scan sandbox failed |
| `scanner-unsupported` | No supply-chain scanner exists yet for the ecosystem |
| `base-moved` | The default branch moved while the candidate was assessed |
| `commit-failed` | GitHub rejected the update branch commit |

Older runs and runs without validated evidence return `summary: null`.

Timestamps use ISO 8601 strings in UTC. Poll while the status is `queued` or
`in_progress`, and stop when it is `completed` or `failed`. Back off between
requests and respect API rate limits rather than polling continuously.
Unknown runs and runs belonging to another organization return `404 not_found`.

## Publication is asynchronous

A `completed` run does not guarantee that a pull request exists. A run can
finish without eligible updates, or proposals can be skipped by policy,
the pre-PR supply-chain scan, or publication safeguards. Publication happens asynchronously after update
generation and evaluation.

To trigger automation only when an approved update reaches GitHub, subscribe
to the existing `dependency_update.published` organization webhook. It includes
the repository, persisted dependency update pull request ID, title, and
pull request URL. The run ID is `null` if no matching run was found. It is a
publication event, not a run-completion event. See
[Webhooks](https://www.superagent.sh/docs/webhooks) for the payload, signatures, and retries.

## MCP tools

The same operations are available through the [Superagent MCP server](https://www.superagent.sh/docs/mcp):

| REST operation | MCP tool | Arguments |
| --- | --- | --- |
| Start a run | `trigger_dependency_updates` | `repository_id` (number), optional `scope` (`vulnerabilities`, `versions`, or `all`) |
| Retrieve run status | `get_dependency_update` | `run_id` (UUID string) |

Omitting MCP `scope` uses the repository's saved scope. MCP has the same
organization scoping, active-run conflicts, and asynchronous publication
behavior as REST.

## Errors

| HTTP status | Code | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | Invalid repository ID, run UUID, JSON body, or scope |
| `401` | `unauthorized` | Missing or invalid organization API key |
| `404` | `not_found` | Repository or run is missing or belongs to another organization, or the repository or GitHub App installation is inactive |
| `409` | `conflict` | A repository run is already active |
| `500` | `internal_error` | Unexpected server failure |

## Next steps

- [Configure Secure Dependency Updates](https://www.superagent.sh/docs/security-workers/secure-dependency-updates)
- [Subscribe to published updates with Webhooks](https://www.superagent.sh/docs/webhooks)
- [Use Superagent MCP](https://www.superagent.sh/docs/mcp)

---
Source: https://www.superagent.sh/docs/api/dependency-updates
Index: https://www.superagent.sh/llms.txt