Send evidence through the API

Use the versioned API to connect existing CI jobs and product Mission Controls to BuildVouch. A submission is an immutable claim with provenance; it is not automatically a verified security result.

Create a scoped token

An organisation owner opens an application's Connection tab, verifies an authenticator, and creates a token. Choose evidence:write for ingestion and read only when the integration needs to read that application.

Copy the token once into your CI secret store. BuildVouch stores a SHA-256 hash, safe suffix, scope and expiry. Tokens expire after 30 days and may be revoked sooner. Do not place tokens in source code, URLs, screenshots or logs.

Submit a record

The examples use placeholders. Replace them in your CI environment.

bash

curl --fail-with-body "$BUILDVOUCH_URL/api/v1/products/$APPLICATION_ID/evidence" \
  -H "Authorization: Bearer $BUILDVOUCH_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @evidence.json

json

{
  "environment": "ci",
  "commit_sha": "FULL_40_CHARACTER_COMMIT_SHA",
  "repository": "YOUR_ORG/YOUR_REPOSITORY",
  "control_key": "tenant_isolation",
  "result": "passed",
  "summary": "Two-tenant isolation suite completed; source report retained in CI.",
  "source_url": "https://github.com/YOUR_ORG/YOUR_REPOSITORY/actions/runs/RUN_ID",
  "request_key": "YOUR_UNIQUE_RUN_AND_CONTROL_KEY"
}

Only passed, failed and unknown are accepted result values. Submit evidence metadata and a protected source reference. Do not submit raw logs, personal data, exploit payloads or credential values.

Verification boundary

API records are stored with origin api and verification unverified. Manual workspace entries use origin manual. Neither can satisfy the release gate. The read-only GitHub connector independently checks the configured source and produces separate verified records.

Replay handling

Use one stable request_key for the same source event and control. Repeating the same accepted payload returns the original record. Reusing that key with different content returns a conflict. Retries should use exponential backoff for transient failures and respect Retry-After on 429.

Responses

Responses contain data or an error with code and message, plus request_id. Authentication is required. Keys are bound to one application and organisation. JSON bodies are limited to 64 KiB. Valid token traffic is limited to 120 requests per minute; ingestion performs a second authorization check and therefore consumes another rate-limit unit.

Read the downloadable OpenAPI contract for the endpoint catalogue.

Connect CI to a release approval

The repository includes scripts/submit-evidence.mjs and scripts/check-release.mjs for Node 24. Configure BUILDVOUCH_URL, BUILDVOUCH_TOKEN and the appropriate application or release identifiers through your CI secret store.

Run node scripts/submit-evidence.mjs evidence.json to append a claim. Run node scripts/check-release.mjs immediately before a deployment step, with BUILDVOUCH_RELEASE_ID, BUILDVOUCH_COMMIT_SHA and BUILDVOUCH_ENVIRONMENT set to the exact candidate. Use a separate read token for this check.

The release check fails if the request is unavailable, the evidence changed, the approval expired, the SHA or environment differs, or the independent approval is missing. BuildVouch does not execute the deployment. Your pipeline must honour the script's nonzero exit code and deploy exactly the approved candidate.