Skip to main content

API usage

An API call uses the corresponding operation's pricing: most granular searches start at 1 credit, granular WHOIS starts at 3, and favicon similarity costs 3. Unified search charges 1 credit per target dataset on the initial query, including WHOIS; paging has its own pricing. See Credits. The Profundis API lets you query the search engine from your workflows and tools.

Using the API requires a paid plan (Solo or Professional) or unused credits from a credit pack. The monthly credits of a Free account don't count, so a new Free account can't create a token.

The OpenAPI documentation is available here.

tip

Before using the example commands below, define your API key in a variable. Replace xxx by the correct value. See how to create a key and save its one-time secret.

API_KEY=xxx

Authentication​

Send your personal API key in one of these headers:

X-API-KEY: <YOUR_API_KEY>
Authorization: Bearer <YOUR_API_KEY>

A missing, invalid, expired or revoked key returns HTTP 401. Create a separate named key for each integration; you can have five active personal keys. See Generate a token for expiration, recent authentication and rotation with up to 24 hours of overlap.

Existing 64-character keys remain valid. Using ?api_key= in the URL is deprecated and works only during the 90-day transition from that deployment's keys-v2 migration. During the transition, query-authenticated responses include Deprecation and Sunset headers; use Sunset for the cutoff rather than assuming a universal date. Switch to a header before that cutoff. This also applies to alert streams.

The following query performs a search and retrieves all the available information.

curl "https://api.profundis.io/api/v2/common/data/hosts" \
  -H "X-API-KEY: $API_KEY" \
  -H "content-type: application/json" \
  -X POST \
  -d '{
    "raw_query": "host:*.example.com",
    "include": "all",
    "aggregate": false,
    "results_per_page": 50,
    "page": 1
  }'

In the body, raw_query is your search query, include is all or a comma-separated list of fields to return, results_per_page is 10, 30 or 50, and page starts at 1. Keep aggregate set to false for normal row results.

You can filter the type of information you want to retrieve. Notice the host,resolution,port below.

curl "https://api.profundis.io/api/v2/common/data/hosts" \
  -H "X-API-KEY: $API_KEY" \
  -H "content-type: application/json" \
  -X POST \
  -d '{
    "raw_query": "host:*.example.com",
    "include": "host,resolution,port",
    "aggregate": false,
    "results_per_page": 50,
    "page": 1
  }'

The following command performs a DNS search through the Profundis API.

curl "https://api.profundis.io/api/v2/common/data/dns" \
  -H "X-API-KEY: $API_KEY" \
  -H "content-type: application/json" \
  -X POST \
  -d '{
    "raw_query": "host:*.example.com",
    "include": "all",
    "aggregate": false,
    "results_per_page": 50,
    "page": 1
  }'

OpenAPI documentation​

The deployed production contract is available as JSON or YAML. It reflects the production deployment, not unreleased staging features.

The revised OpenAPI 3.0.3 personal API contract is available on staging as JSON or YAML after deployment. It covers all 33 business operations currently registered under /api/v2/common and /api/v2/sse/common: 18 data operations (including search, Pivot, favicon matching and enrichment), seven export operations, four saved-Pivot operations, account refresh and three alert-stream operations. CORS preflights are excluded.

This is not an inventory of all website routes. Anonymous previews, account/login and OAuth authorization-server endpoints, browser sessions, organization service keys and administration are separate surfaces. See the dedicated Pivot guide, alert integration guide and organization service API.

See Search and vulnerability associations for the staging CVE/KEV additions, streaming outcomes and matched product/version explanations.

Browser session endpoints use a separate session and Exposition contract. Personal API keys cannot be substituted for its session cookie or CSRF protection. Organization service keys use the scoped service API.

The revised contract corrects older paths: domain details use /api/v2/common/data/domains/details. IP intelligence and pipelines are session tools at /api/v2/data/ip/intelligence and /api/v2/data/auth/pipeline/search; the old /common paths in Swagger were not registered routes. Portfolio analysis and favicon extraction are documented on the session surface. The public caller-IP route is /api/v2/data/my-ip. Existing production routes are not renamed by this documentation change.

Organization API​

Personal API credentials do not select an organization payer. For client-scoped jobs, credit ceilings, reports and monitoring, use the scoped service API with an organization service key.

Last updated on