API reference
Read your in-market accounts with their evidence, and report outcomes back, from your own tools. Every read is scoped to your workspace: you only ever see your own accounts.
Get a key
Go to Integrations, open API & MCP, and choose Create key. Name it, choose its available access, and copy the key when it is shown. An Owner or Admin can create and revoke keys.
Authentication
Send the key as a Bearer token on every request. The base URL is https://vergio.ai/api/v1.
curl "https://vergio.ai/api/v1/accounts?limit=25" \
-H "Authorization: Bearer $VERGIO_API_KEY" \
-H "Idempotency-Key: replace-with-a-stable-request-id"Scopes
A call needs the scope listed on its operation. The self-serve key form currently offers Read access, Write outcomes, and Generate reports. Read access grants read:accounts and automatically adds read:watch. The other scopes below define the public authorization contract but are not selectable for a new key in the current form.
Claude sign-in uses a separate role-derived grant: active members receive day-to-day account, watch, outcome, report, outreach, deal, and contact access; wallet reads follow workspace visibility, and webhook management remains Owner/Admin-only.
| Scope | What it allows |
|---|---|
read:accounts | Search scored accounts and read account, deal, contact, and signal data. The published current-list operation is unavailable in wallet-live. |
read:wallet | Read wallet balance, usage, pricing, approvals, and standing rules. |
read:watch | Read managed, self-directed, and client watch state, health, events, receipts, and briefs. |
write:watch | Resize or cancel managed watch, and add or remove self-directed and client watches. |
write:outcomes | Record outreach outcomes (discovery, qualifying, won, and so on). |
write:deals | Create, update, move, and note deals, and set an account's status. |
write:contacts | Create, update, and discover contacts on your accounts. |
generate:reports | Request growth reports when the operation is available. |
write:outreach | Enroll and stop stores in outreach cadences during the approved pilot. |
manage:webhooks | Register endpoints for signed deal, contact, store, signal, and watch-health events. |
Rate limits
Limits are per key, per minute, by the kind of call. Over the limit returns 429with a Retry-After header. These are the current wallet-live ceilings.
| Call type | Limit per minute |
|---|---|
| read | 120 |
| write | 20 |
| report | 5 |
Errors
Errors use the RFC 7807 problem shape with a application/problem+json content type: type, title, status, and detail.
| Status | Meaning |
|---|---|
400 | Invalid parameters, body, cursor, or required request identity. |
401 | Missing or invalid API key. |
403 | The key lacks the scope this call needs. |
404 | The resource is not visible to this workspace, or the operation is unavailable. |
409 | The request conflicts with existing state, funding, or an earlier request identity. |
422 | The request is valid JSON but cannot be completed with the supplied resource. |
429 | Rate limit exceeded. Retry after the seconds in the Retry-After header. |
503 | Authorization, policy, or source data is temporarily unavailable. |
Pagination
Bounded list operations use cursors. Read next_cursor from a response and pass it back as the documented cursor parameter to fetch the next page. A null next_cursor means you have reached the end.
Idempotency
Every operation that lists a required Idempotency-Key header needs a stable logical request ID. Repeating the same ID and input replays the original result. Reusing it with changed input returns a conflict instead of applying a second mutation.
Availability
The reference labels operations that are pilot-only, activation-gated, or unavailable. Availability is checked again when you call the operation. A published compatibility contract is not a promise that the operation is active for the current workspace state.
OpenAPI
The full machine-readable spec is at /api/v1/openapi.json. Every endpoint below has its own page with request and response samples.