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.

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:

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

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

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

Run fields

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