Quick Start - Osintly Documentation

This guide walks through the minimal API flow using cURL.

You need a valid bearer token first. See Authentication.

1) Check service health

curl -X GET "https://api.osint.ly/health"

2) Validate your token

curl -X GET "https://api.osint.ly" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

2.1) Optional: test Radar (free plan)

Radar access is free, but still requires an authenticated API key.

curl -X GET "https://api.osint.ly/radar/breaches?limit=2&sortBy=recently-added" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

3) Create a search

curl -X POST "https://api.osint.ly/search" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "type": "Email Address",
      "value": "[email protected]"
    },
    "features": {
      "breached_accounts": true,
      "registered_accounts": "include"
    },
    "cache": {
      "mode": "prefer"
    }
  }'

Save the returned search.id for the next calls.

Optional: run selected modules only

curl -X POST "https://api.osint.ly/search" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "type": "Email Address",
      "value": "[email protected]"
    },
    "modules": {
      "mode": "selected",
      "ids": [
        "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
        "95c36c17-f76e-4911-bd4e-8ea57515b2fb"
      ]
    }
  }'

If modules is omitted, Osintly uses the default module set for the selected search type.

4) Stream progress (SSE)

curl -N -X GET "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

You receive incremental events while the search is running. Concrete output example:

event: connected
data: {"search_id":"SEARCH_ID","timestamp":"2026-06-23T14:10:01.000Z"}

event: module.result
data: {"search_id":"SEARCH_ID","module":{"id":"github","name":"GitHub"},"card":{"github_001":{"username":"target"}},"timestamp":"2026-06-23T14:10:03.000Z"}

event: search.finished
data: {"search_id":"SEARCH_ID","status":"completed","totals":{"module_results":1},"timestamp":"2026-06-23T14:10:09.000Z"}

Concrete BYOK stream output example:

event: byok.result
data: {"search_id":"SEARCH_ID","provider":"osint_industries","card":{"source":"github","username":"target"},"timestamp":"2026-06-23T14:11:03.000Z"}

event: byok.finished
data: {"search_id":"SEARCH_ID","provider":"osint_industries","status":"success","resultCount":6,"timestamp":"2026-06-23T14:11:08.000Z"}

If modules are sharded across runners, you can also receive search.progress messages such as:

event: search.progress
data: {"search_id":"SEARCH_ID","status":"running","message":"shard 1/3 progress 5/12","result_cards_count":17,"timestamp":"2026-06-23T14:11:04.000Z"}

5) Fetch search state

curl -X GET "https://api.osint.ly/search/SEARCH_ID" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

6) Fetch final structured results

curl -X GET "https://api.osint.ly/search/SEARCH_ID/results" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

7) Fetch leak source payloads

# List available leak sources for a search
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results/leaks" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

# Fetch one source (optional page)
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results/leaks/snusbase?page=1" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

8) Optional: receive results by webhook

Provide delivery.webhook.url (and optionally delivery.webhook.secret) when creating the search:

{
  "query": {
    "type": "Email Address",
    "value": "[email protected]"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}

When the search completes, your endpoint receives a JSON payload with:

searchId
status (finished or error)
finishedAt
search metadata (id, value, type, options, created_at)
summary counts
links to retrieve state, results, BYOK details, and leaks

The webhook is a lightweight completion notification. Use the returned links to fetch the full normalized payloads from the API. Full payload details: Webhooks

9) Recommended: clean up completed searches

After you have fetched and stored the data you need, delete completed searches you no longer need:

curl -X POST "https://api.osint.ly/search/delete" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["SEARCH_ID"]
  }'

Use this only after the search is terminal. Deletion requests are all-or-nothing and support up to 100 IDs per call. Cleanup guidance: Search Retention

Rate limits and usage

Use GET /usage to read current global and daily usage windows.

curl -X GET "https://api.osint.ly/usage" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"

If you receive 429, respect Retry-After and X-RateLimit-Reset headers before retrying.

Terms and ethics

Terms of Use: https://osint.ly/terms
Ethics Policy: https://osint.ly/ethics

Next steps

Explore the OpenAPI endpoint docs in the Endpoints group
Read Domains for type values and request patterns

​1) Check service health

​2) Validate your token

​2.1) Optional: test Radar (free plan)

​3) Create a search

​Optional: run selected modules only

​4) Stream progress (SSE)

​5) Fetch search state

​6) Fetch final structured results

​7) Fetch leak source payloads

​8) Optional: receive results by webhook

​9) Recommended: clean up completed searches

​Rate limits and usage

​Terms and ethics

​Next steps

1) Check service health

2) Validate your token

2.1) Optional: test Radar (free plan)

3) Create a search

Optional: run selected modules only

4) Stream progress (SSE)

5) Fetch search state

6) Fetch final structured results

7) Fetch leak source payloads

8) Optional: receive results by webhook

9) Recommended: clean up completed searches

Rate limits and usage

Terms and ethics

Next steps