REST API
Read your in-market accounts, manage your pipeline, and report outcomes back from your own tools with a scoped key.
The REST API lets your own tools read your Vergio account, manage your pipeline, and use the operations available to your workspace. Every call is workspace-scoped.
Get started
Create a key. In your workspace, go to Integrations > API & MCP > Create key. The self-serve
screen currently offers Read access, Write outcomes, and Generate reports. Read access
grants read:accounts and automatically adds read:watch.
See API keys.
Call the API. Send the key as a Bearer token to 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"What you can do
- Search and page through your scored accounts.
- Read one account's detail and its signal history.
- Read managed-watch and client-watch state with a read key.
- Report an outcome, which becomes a learning label that improves your rankings.
- Manage your pipeline: create and update deals, move them through stages, add notes, and set an account's status.
- Manage contacts: add, update, and find the people behind an account.
- Use wallet and supervision contracts through Claude connector OAuth where the signed-in member's workspace role grants access.
- Use outreach operations only during an approved Outreach Studio pilot.
The reference labels each operation from the capability manifest. Unavailable operations remain published for compatibility but cannot be called in the current wallet-live product state. Pilot operations require approved pilot access. Publishing an operation does not make it live.
The OpenAPI contract lists the protocol scope required by every operation. Some scopes, including wallet, watch write, pipeline write, contact write, event-notification, and outreach scopes, are not selectable for a new self-serve API key. Claude connector OAuth derives its grants from the signed-in member's workspace role.
For account rows, delivered_to_agent proves delivery to an agent, not a human view.
selected_for_first_party_surface proves selection for Vergio's surface, not rendering or viewing.
Write back operator decisions with record_outcome or set_account_status.
Get notified about changes
Instead of polling, register an event-notification endpoint so Vergio calls your own URL when supported deal, contact, store, or watch state changes.
Register an event-notification endpoint. Send your https URL, and optionally the events you care about (leave them
out to receive all). Vergio returns a signing secret once, so store it then.
Verify each call. Every delivery carries a signature built from your secret, so you can confirm it really came from Vergio. Failed deliveries are retried with backoff.
Current event types are deal.created, deal.updated, deal.stage_changed, contact.created,
store.entered, store.exited, store.signal, and watch.health_changed. The exact request and
response shapes are in the API reference.
Full reference
The complete reference covers wallet-live rate limits, cursor pagination, RFC 7807 errors, required idempotency headers, availability, and every endpoint with copy-ready samples in curl, TypeScript, and Python.
Updated July 28, 2026