---
title: "Find published secrets across six public artifact sources"
method: POST
path: "/v1/metered/secret-scan"
tags: ["Secrets and non-human identity"]
---

# Find published secrets across six public artifact sources

`POST /v1/metered/secret-scan`

## Request

- Base URL: `https://api.relayshield.net`
- URL: `https://api.relayshield.net/v1/metered/secret-scan`
- Auth: one of:
  - API key in header `X-RS-API-KEY`
  - HTTP bearer

Scans GitHub repositories plus npm, PyPI, Docker Hub, Hugging Face and Postman public workspaces and collections for secrets already published against your domain. Secrets ship inside released packages and images constantly, and repo-only scanners never see them. Every hit is verified against the matching credential pattern before it is reported, so a docs example or a placeholder is not billed to you as a CRITICAL.

**Billing.** $0.35 per successful call. Failed calls are never billed. Charged against prepaid credits when the balance covers it, otherwise metered to your card. Threat Intelligence subscribers and AWS Marketplace bundle customers call this at no extra charge.

**Note.** Artifact discovery runs under a 75-second budget. If it is exhausted, remaining sources are skipped and `coverage[].sources` reports exactly what ran -- reduced coverage is stated rather than returned as a false all-clear. A partial scan is never cached, so a rate-limited moment cannot be frozen in as a 24-hour clean result.

## Request body

- object: At least one of: `domain`, `vendor_domains`.
  - `domain` string: Your own domain.
  - `vendor_domains` string[]: Additional supply-chain domains.
  - `include_artifact_sources` boolean: When false, only GitHub is scanned. Defaults to true. Set false for a faster, repo-only scan.

## Response `200`

Success. `ok` is true and `data` holds the result.

- object
  - `ok` true, required
  - `data` object, required
    - `domains_checked` integer: Domains actually scanned. Capped at 5 after deduplication.
    - `found` boolean: True when at least one verified secret was found.
    - `findings` object[]: Findings, sorted most severe first.
      - `source` 'github' | 'npm' | 'pypi' | 'dockerhub' | 'huggingface': Artifact source it was found in.
      - `type` string: Credential type, e.g. aws_access_key, github_pat, stripe_secret_key.
      - `description` string: What the credential grants.
      - `severity` 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW': Severity of the credential type.
      - `repo` string: Repository or package the secret is in.
      - `file` string: Path within the artifact.
      - `url` string: Direct link to the match.
      - `preview` string: Redacted context. Never the secret value.
      - `domain` string: Which supplied domain this finding belongs to.
      - `surfaced_by` string: Present only when the query that surfaced the hit differs from the credential type finally classified.
    - `highest_severity` 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'null', nullable: Highest severity across findings. null when none.
    - `coverage` object[]: Per-domain scan coverage, reported so a caller can tell a fresh all-clear from a stale one.
      - `domain` string: Domain.
      - `cached` boolean: True when served from the 24-hour cache rather than freshly scanned.
      - `sources` string[]: Sources that actually ran for this domain.
    - `recommendation` string: Remediation text.
    - `checked_at` string, date-time: ISO 8601 UTC timestamp of when this check ran.

## Other responses

- `400`: Neither `domain` nor `vendor_domains` supplied.
- `401`: Missing or invalid API key.
- `402`: No credits and no active subscription. The response carries `topup_url`.
- `405`: Wrong HTTP method. Every endpoint is POST.

---

[API](https://skmtc.dev/relayshield/apis/relayshield-api.md) · [All operations](https://skmtc.dev/relayshield/apis/relayshield-api/llms.txt) · [OpenAPI document](https://skmtc.dev/relayshield/apis/relayshield-api/revisions/4d4721b936dd?raw)