> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periphery.exposed/llms.txt
> Use this file to discover all available pages before exploring further.

# API recipes

> Common Periphery API workflows: paginate search results, fetch full app records, and automate safely around rate limits.

These examples assume `PERIPHERY_API_KEY` is already set in your environment. See [Authentication](/api/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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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](/api/limits-and-errors) for the complete error table.