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
Create a key in your workspace under Settings, then API keys. Name it, choose its scopes, and copy the key when it is shown (it is shown once). 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/lists/current" \
-H "Authorization: Bearer $VERGIO_API_KEY"Scopes
Each key carries only the scopes you grant it. A call needs the scope listed on its endpoint.
| Scope | What it allows |
|---|---|
read:accounts | Read your weekly list, search scored accounts, and read account detail and signals. |
write:outcomes | Record outreach outcomes (contacted, replied, won, and so on). |
generate:reports | Generate growth reports through the API (where enabled for your plan). |
Rate limits
Limits are per key, per minute, by the kind of call. Over the limit returns 429with a Retry-After header. Trial keys get a quarter of the paid ceiling.
| Call type | Paid (per minute) | Trial (per minute) |
|---|---|---|
| read | 120 | 30 |
| write | 20 | 5 |
| report | 5 | 1 |
Errors
Errors use the RFC 7807 problem shape with a application/problem+json content type: type, title, status, and detail.
| Status | Meaning |
|---|---|
401 | Missing or invalid API key. |
403 | The key lacks the scope this call needs. |
404 | No such account for your workspace. |
429 | Rate limit exceeded. Retry after the seconds in the Retry-After header. |
Pagination
Listing accounts is cursor-paginated. Read next_cursor from a response and pass it back as the cursor query parameter to fetch the next page. A null next_cursor means you have reached the end.
Idempotency
When recording an outcome, send a stable Idempotency-Key header. Retrying the same key returns the original result instead of recording the outcome twice.
OpenAPI
The full machine-readable spec is at /api/v1/openapi.json. Every endpoint below has its own page with request and response samples.