API Reference
Complete REST API for the Adrata platform.
Access companies, people, buyer groups, opportunities, and intelligence data. This page mirrors the current API mount, key format, rate-limit headers, request IDs, idempotency behavior, and webhook paths.
Authentication
API requests accept workspace API keys in the Authorization Bearer header, with x-api-keyalso supported. Generate API keys from your workspace Settings → API Keys.
Key prefix
Keys generated by the current API start with ak_. The full secret is only shown once.
Bearer or header
Use Authorization: Bearer or x-api-key with the same key.
Sandbox
Use a dedicated test workspace for sandbox integrations. Test workspaces use the same API surface, auth, idempotency, rate-limit headers, and OpenAPI contract as production data workspaces while keeping records isolated.
Scopes
Keys carry scope strings. Enforcement is route-specific, so check each endpoint before relying on a scope boundary.
Base URL
The canonical versioned base includes /api/v1. Do not omit /api when configuring clients.
SDKs and OpenAPI
OpenAPI 3.x JSON is the source of truth for generated clients and agent tools. Generate typed clients directly from the live spec, pin the generated output in your app, and regenerate when you adopt a new API version.
Sandbox Workspaces
Use a dedicated test workspace for sandbox integrations. Test workspaces use the same API surface, auth, idempotency, rate-limit headers, and OpenAPI contract as production data workspaces while keeping records isolated. Keep one API key per environment, give test keys the minimum scopes they need, and send Idempotency-Key on every write your test runner may retry.
Rate Limits
Rate limits use 60-second windows. The general production tier is 600 requests/minute for authenticated API traffic; stricter tiers apply by route.
Full rate-limit guide| Tier | Production limit | Scope |
|---|---|---|
| General API | 600 requests/minute for authenticated API traffic | Authenticated API traffic |
| Public API | 60 requests/minute per IP for /api/v1/public endpoints | Unauthenticated public records |
| Auth / agent registration | 5 requests/minute per IP for auth and agent registration | Brute-force protection |
Rate-limit state is returned with lowercase header names:
On 429, back off until the larger of retry-after seconds or x-ratelimit-reset. Successful responses include the same limit, remaining, used, reset, and scope headers so agents can slow down before they hit the hard cap.
Request IDs and Idempotency
Send x-request-id or adrata-request-id to carry a trace ID. Adrata echoes both response headers and adds request IDs to JSON error bodies.
Mutating authenticated requests may include Idempotency-Key. Cached responses live for 24 hours; replayed responses include x-idempotent-replay: true.
Reusing the same key with a different method, path, query, or body returns an idempotency conflict instead of executing a second mutation. If the first request is still running, the duplicate receives an in-progress response and should retry the same request after a short delay.
Webhooks
Outbound webhook subscriptions are managed at /api/v1/webhooks. Inbound producer signals use /api/v1/webhooks/inbound/{vendor_id}/{workspace_id}.
Inbound producer webhooks are HMAC-authenticated with x-webhook-signature and x-webhook-timestamp. Stripe and email webhooks are platform integrations, not customer subscription endpoints.
Pagination
List endpoints use cursor-based pagination. Pass limit and cursor as query parameters.
Error Handling
Errors return a consistent JSON structure with an HTTP status code, error type, and human-readable message.
| Status | Error | Meaning |
|---|---|---|
| 400 | bad_request | Invalid parameters or request body |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Key lacks required permission scope |
| 404 | not_found | Resource does not exist |
| 429 | rate_limited | Too many requests. Check retry-after and x-ratelimit-reset headers |
| 500 | internal_error | Server error. Retry with exponential backoff |
Code Examples
Search for companies using the API. These examples show the same request in curl, TypeScript, and Python.
Endpoint Reference
All endpoints are available under https://api.adrata.com/api/v1. Click an endpoint group to see details.
Companies
Search, list, create, and update company records. Includes enrichment data, intelligence scores, and buyer group coverage.
People
Manage contacts and leads. Access enrichment data, engagement history, and stakeholder role classifications.
Buyer Groups
Map buying committees for target accounts. Get stakeholder roles, coverage gaps, and engagement signals.
Opportunities
Full pipeline access. Create, update, and track opportunities with deal health scores and stage progression.
Intelligence
AI-powered analysis endpoints. Generate deal summaries, risk assessments, next-step recommendations, and competitive intelligence.
Search
Unified search across all entities. Full-text search with filters, facets, and relevance ranking.
Full Example: Create a Buyer Group
This example creates a buyer group for a target account and retrieves the mapped stakeholders.
Ready to build?
Get your API key and start making requests in minutes.