API overview

Base URLs, response conventions, endpoint families, and the machine-readable OpenAPI document.

Base URL

https://api.ploid.com/v1

All public operations other than API discovery require one of the authentication modes declared by that operation. External server integrations normally use an API key. The OpenAPI document itself is intentionally unauthenticated so clients can inspect the contract before creating a key.

curl https://api.ploid.com/v1/account/usage \
  -H "Authorization: Bearer $PLOID_API_KEY"

OpenAPI 3.1

Download the current machine-readable API contract from:

https://api.ploid.com/v1/openapi.json

No authorization header is required for this URL.

Endpoint families

Family	Primary endpoint	Use it for
Agent	`POST /v1/agent`	Model-led research and connected-app work
Search	`POST /v1/search`	Fast synchronous people retrieval
Enrichment	`POST /v1/enrich`	Known LinkedIn identity and contact enrichment
Social	`POST /v1/socials`	Social profiles and supported public LinkedIn reads
Account	`/v1/account/*`	Credits, usage context, and revoking the calling key
People Sets	Private preview	Not currently available to public API keys

The account surface consists of GET /v1/account/credits, GET /v1/account/usage, and DELETE /v1/account/key. The delete operation revokes the same key that authenticated the request.

Standard success envelope

Most JSON endpoints return a top-level data value and a meta object.

{
    "data": {},
    "meta": {
        "request_id": "req_..."
    }
}

Version policy

The /v1 response envelopes are stable. Ranking, providers, and cache strategy may evolve without a version change when field names and response semantics remain compatible.

Server-side only

Do not call the Ploid API directly from public browser code. Keep the API key on your server and expose only the application-specific operation your frontend needs.

Failures and limits

Every surface uses the same public error envelope and plan limits. Individual endpoint pages list their additional validation errors, budgets, and route-specific ceilings.