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.

All requests require an organization API key sent as a bearer token in the Authorization header, as described in the REST API. Repositories and runs are scoped to the API key's organization.

Endpoints

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:

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

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

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

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

Run fields

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:

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 for the payload, signatures, and retries.

MCP tools

The same operations are available through the Superagent MCP server:

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

Next steps

• Configure Secure Dependency Updates
• Subscribe to published updates with Webhooks
• Use Superagent MCP