> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


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

# Contributor Trust

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 [REST API](https://www.superagent.sh/docs/api). See the [Contributor Trust overview](https://www.superagent.sh/docs/security-workers/contributor-trust) 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.

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

### Response

`200 OK`

```json
{
  "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 **Webhooks**, then see [Webhooks](https://www.superagent.sh/docs/webhooks)
for signatures, retries, and payloads.

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

### Response

`202 Accepted`

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

```bash
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](https://www.superagent.sh/docs/webhooks#contributor-trust-payload) for the complete event shape.

## MCP tools

The same operations are available through the [Superagent MCP server](https://www.superagent.sh/docs/mcp):

| 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

- [Configure Contributor Trust](https://www.superagent.sh/docs/security-workers/contributor-trust)
- [Subscribe to trust events with Webhooks](https://www.superagent.sh/docs/webhooks)
- [Connect GitHub](https://www.superagent.sh/docs/connect/github)

---
Source: https://www.superagent.sh/docs/api/contributor-trust
Index: https://www.superagent.sh/llms.txt