> 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.

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 one field:

| Field | Type | Description |
| --- | --- | --- |
| `scope` | string | Optional: `vulnerabilities`, `versions`, or `all`. Defaults to the repository's saved dependency update scope |

- `vulnerabilities` targets known vulnerable dependencies.
- `versions` checks direct dependencies for available versions.
- `all` runs vulnerability remediation first, then checks version updates.

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",
    "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`.

## 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` |
| `proposal_count` | number | Number of generated proposals recorded by the run |
| `skipped_count` | number | Number of skipped update tasks or proposals |
| `published_count` | number | Currently always `0`; asynchronous publication does not update this field. Use `dependency_update.published` webhooks to confirm individual pull requests |
| `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 |

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 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, proposal and run IDs, title, and pull request URL. 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