API recipes

These examples assume PERIPHERY_API_KEY is already set in your environment. See Authentication for key creation and headers.

Page through every result

Search returns 50 hits per page. This loop prints every matching hostname and waits between requests to stay within the one-request-per-second limit.

query='acme.com'
page=1

while :; do
  response="$(
    curl -fsS --get "https://api.periphery.exposed/v1/search" \
      -H "Authorization: Bearer $PERIPHERY_API_KEY" \
      --data-urlencode "q=$query" \
      --data-urlencode "p=$page"
  )"

  jq -r '.hits[].hostname' <<<"$response"

  total="$(jq -r '.total' <<<"$response")"
  if (( page * 50 >= total )); then
    break
  fi

  page=$((page + 1))
  sleep 1
done

A page past the end is also safe: it returns the same total and an empty hits array.

Fetch the full record for one hit

Search hits are summaries. Use the hostname as the stable identifier when you need the screenshot URL, extracted text, emails, or credential findings.

hostname='acme-dashboard.vercel.app'

curl -fsS "https://api.periphery.exposed/v1/apps/$hostname" \
  -H "Authorization: Bearer $PERIPHERY_API_KEY" |
  jq

A 404 means there is no current live app record for that hostname. Hosts that Periphery later proves dead also return 404.

Find apps with verified credential findings

The has:creds filter keeps apps with at least one verified credential finding.

curl -fsS --get "https://api.periphery.exposed/v1/search" \
  -H "Authorization: Bearer $PERIPHERY_API_KEY" \
  --data-urlencode "q=acme.com has:creds" |
  jq -r '.hits[] | [.hostname, .provider] | @tsv'

Use the app endpoint only for records you actually need to inspect. Its credentials array contains raw strings when findings exist.

Keep credential-bearing responses out of logs

API app records can contain raw credential strings. Avoid dumping complete responses into CI logs, chat systems, tickets, analytics, or third-party AI tools unless your organisation has explicitly approved that data flow. Select only the fields the next system needs. For example:

curl -fsS "https://api.periphery.exposed/v1/apps/acme-dashboard.vercel.app" \
  -H "Authorization: Bearer $PERIPHERY_API_KEY" |
  jq '{hostname, provider, status, lastSeen, hasVerifiedCreds, verifiedDetectors}'

This keeps the raw credentials array out of the output.

Retry the errors that are retryable

429 rate limit: 1 request per second: wait at least a second before the next request.
502 search backend error: retry after a short delay.
401 and 403: fix the key or plan instead of retrying.
404 app not found: treat the record as unavailable rather than repeatedly polling it.

See Limits and errors for the complete error table.

Using the API

Endpoints

Page through every result

Fetch the full record for one hit

Find apps with verified credential findings

Keep credential-bearing responses out of logs

Retry the errors that are retryable

​Page through every result

​Fetch the full record for one hit

​Find apps with verified credential findings

​Keep credential-bearing responses out of logs

​Retry the errors that are retryable

Page through every result

Fetch the full record for one hit

Find apps with verified credential findings

Keep credential-bearing responses out of logs

Retry the errors that are retryable