Adrata Developers
Scopes & Versioning
The public contract for least-privilege access, date-versioned upgrades, deprecations, and breaking-change windows.
curl https://api.adrata.com/api/v1/companies \
-H "Authorization: Bearer $ADRATA_API_KEY" \
-H "Adrata-Version: 2026-05-23" \
-H "X-Request-ID: 01JZ7Y8M9W4KZ9V3GZJY9D7F2A"Scope policy
Every public API key, OAuth access token, and agent token should carry the narrowest scopes needed for its workflow. Scope checks are route-family based and are recorded in audit logs with the human user, OAuth client, or agent principal that made the request.
| Primitive | Use | Key APIs |
|---|---|---|
| read:companies | Read company and account records, enrichment summaries, and relationship context. | GET /api/v1/companies |
| write:companies | Create and update company records, custom fields, and enrichment requests. | POST/PATCH /api/v1/companies |
| read:people | Read people, leads, contacts, stakeholders, and relationship intelligence. | GET /api/v1/people |
| write:people | Create and update people, contact data, lead status, and person enrichment. | POST/PATCH /api/v1/people |
| read:buyer-groups | Read buying committees, roles, influence maps, and intro paths. | GET /api/v1/buyer-group |
| write:buyer-groups | Modify buyer room membership, roles, connectors, and intro requests. | POST/PATCH /api/v1/buyer-group |
| write:enrichment | Run company, person, and GTM intelligence enrichment tasks. | POST /api/v1/agent-tasks |
| read:analytics | Read pipeline, conversion, activity, forecast, retention, and expansion analytics. | GET /api/v1/analytics/* |
| admin:webhooks | Create, test, inspect, replay, and rotate webhook subscriptions. | /api/v1/webhooks |
| admin:api-keys | Create and rotate scoped API keys for workspace integrations. | /api/v1/api-keys |
Version policy
`/api/v1` is stable and date-versioned. Production clients should send `Adrata-Version` with a calendar date and advance deliberately after reviewing the release notes, generated SDK diff, and sandbox fixtures.
If `Adrata-Version` is omitted, Adrata serves the latest stable version and returns the resolved version in the response headers. Unsupported dates return `400 application/problem+json` with a machine-readable error code.
Deprecation policy
Deprecated behavior is announced in the release notes, surfaced with `Deprecation`, `Sunset`, and documentation `Link` headers where possible, and kept available through the published sunset date unless a security or compliance issue requires emergency removal.
Breaking changes require a release-notes entry with a migration path, SDK release notes, and an explicit sunset date. New integrations should use cursor pagination, scoped credentials, idempotency keys on writes, and the current SDK major version.
Production rule
Do not deploy unpinned integrations. Store the Adrata request ID, your own request ID, API version, token principal, and rate-limit bucket for every production workflow.