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 Renovate 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.outcome, not status alone. no_supported_dependencies means no manifests were extracted, not that the repository is vulnerability-free. summary_incomplete and null counts mean evidence is missing, not zero updates. updates_proposed records native candidates, including non-publishing dry-runs; it is not proof of vulnerability removal or policy approval. Older runs and runs without validated evidence return summary: null.

Dry-run publication and dependency availability

New summaries include publication, an optional v1 extension. Use publication.wouldCreatePR for distinct branches whose new-PR eligibility was established after resolution and verification, and wouldUpdatePR for existing pull requests. Do not use raw candidates or proposed branch counts as PR counts. unknownEligibility is explicit when native publication gates cannot be proven without a real branch or status checks; the counts do not guarantee future CI, GitHub acceptance, or merge approval. Inspect complete and blockedReasons. Samples can be truncated without truncating aggregate counts.

lookups separates unavailable dependency identities from their affected occurrences. Many files referencing one private module count as one unavailable dependency, not many distinct failures. An explicit access error is reported separately from a generic no-result, which could also mean missing tags or an unavailable package. Unsupported dynamic references and artifact resolution failures are separate categories. These fields do not broaden repository access.

Older runs omit these extensions or return null. Rerun with dryRun: true after deployment to collect the new evidence.

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, pre-publication Kernel checks, 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 Renovate pull request observation 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