superagent_

// api

Contributor Trust

Retrieve cached contributor trust and start asynchronous scans through the REST API.

Use the Contributor Trust API to retrieve the latest cached score for a GitHub login or start a new asynchronous scan.

All requests require the Bearer authentication described in the API overview. See the Contributor Trust overview for how scores and evidence are produced.

Endpoints

Method Path Description
GET /contributors/{login}/trust Retrieve the latest globally cached result
POST /contributors/{login}/trust-scans Start an asynchronous scan
GET /contributor-trust-scans/{scan_id} Retrieve an organization-scoped scan and its result

GitHub logins are case-insensitive and returned in lowercase. Invalid logins return 400 invalid_request.

Retrieve cached trust

GET /api/v1/contributors/{login}/trust returns the latest globally cached Contributor Trust result. Any valid organization API key can read a cached result; the contributor does not need prior activity in that organization.

curl https://superagent.sh/api/v1/contributors/octocat/trust \
  -H "Authorization: Bearer sk_live_..."

Response

200 OK

{
  "data": {
    "object": "contributor_trust",
    "login": "octocat",
    "score": 91,
    "score_version": "deterministic-v2.1",
    "verdict": "safe",
    "confidence": "high",
    "sub_scores": {
      "identity": 92,
      "behavior": 90,
      "content": 91
    },
    "analyzed_pr_count": 10,
    "public_evidence": [
      {
        "repo": "octocat/hello-world",
        "number": 12,
        "title": "Harden request validation",
        "url": "https://github.com/octocat/hello-world/pull/12",
        "verdict": "clean",
        "files_reviewed": ["src/validator.ts"]
      }
    ],
    "scanned_at": "2026-08-10T12:00:00.000Z"
  }
}

The endpoint returns 404 not_found when no cached result exists.

Trust fields

Field Type Description
login string Normalized GitHub login
score number or null Aggregate score from 0 through 100
score_version string or null Scoring model version
verdict string or null Overall trust verdict
confidence string or null Confidence supported by available evidence
sub_scores object or null Identity, behavior, and content scores
analyzed_pr_count number or null Number of pull requests included in history analysis
public_evidence object[] Source metadata for reviewed pull requests confirmed public when collected
scanned_at string Cache timestamp in ISO 8601 format

Private repository names, private pull request identifiers, patches, signals,
threats, and free-form agent evidence are used internally for scoring and are
not returned by the API. Public evidence includes only GitHub source metadata
and reviewed file names from confirmed public repositories.

Start a scan

POST /api/v1/contributors/{login}/trust-scans starts an asynchronous Contributor Trust scan. The request has no body.

Before starting a scan, the API key's organization must have:

  • an active Superagent GitHub App installation
  • at least one enabled webhook subscribed to contributor_trust.finished

Configure the callback under Settings, then see Webhooks for signatures, retries, and payloads.

curl https://superagent.sh/api/v1/contributors/octocat/trust-scans \
  -X POST \
  -H "Authorization: Bearer sk_live_..."

Response

202 Accepted

{
  "data": {
    "id": "scan_uuid",
    "object": "contributor_trust_scan",
    "login": "octocat",
    "status": "queued",
    "trust": null,
    "error": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-08-10T11:58:00.000Z",
    "updated_at": "2026-08-10T11:58:00.000Z"
  }
}

The endpoint returns 409 conflict when the organization is missing a prerequisite or a scan for the same organization and login is already active. Fresh compatible cache entries can complete without repeating the full analysis.

Retrieve scan status

GET /api/v1/contributor-trust-scans/{scan_id} returns a scan created by the API key's organization.

curl https://superagent.sh/api/v1/contributor-trust-scans/scan_uuid \
  -H "Authorization: Bearer sk_live_..."

status is queued, in_progress, completed, or failed. A completed scan includes the same contributor_trust object under trust. A failed scan includes a safe error.message.

Unknown scans and scans owned by another organization both return 404 not_found.

Completion webhook

Every enabled organization endpoint subscribed to contributor_trust.finished receives the terminal scan result. The event fires for completed and failed scans, uses the normal webhook signature, and follows the standard retry policy.

See the Contributor Trust webhook payload for the complete event shape.

MCP tools

The same operations are available through the Superagent MCP server:

REST operation MCP tool
Retrieve cached trust get_contributor_trust
Start a scan scan_contributor_trust
Retrieve scan status get_contributor_trust_scan

Errors

HTTP status Code Meaning
400 invalid_request Invalid GitHub login or scan ID
401 unauthorized Missing or invalid API key
404 not_found No cached result, or the scan is missing or belongs to another organization
409 conflict Scan prerequisite is missing or a scan is already active
500 internal_error Unexpected server failure

Next steps