Loading developer documentation
Victavio for developers
Search open bids, check fit, see past awards and work your pipeline with the same tools the Victavio Assistant uses. See what is live on our coverage page.
API access is paused while we finish launch checks.
GET /api/v1/context
{
"workspace": "Your business",
"business": { "what_you_do": "..." },
"pipeline": { "counts_by_stage": {} },
"team": { "members": [] },
"rules": ["You submit. We help."]
}Illustration of the context your agent receives. The reference shows the complete response.
From key to first call
curl "https://victavio.com/api/v1/opportunities?q=janitorial&states=TX&limit=5" \
-H "Authorization: Bearer $VICTAVIO_API_KEY"The same permissions and plan limits apply in the app and through your key.
The same permissions and plan limits apply in the app and through your key.
The same permissions and plan limits apply in the app and through your key.
The same permissions and plan limits apply in the app and through your key.
The same permissions and plan limits apply in the app and through your key.
The same permissions and plan limits apply in the app and through your key.
The same permissions and plan limits apply in the app and through your key.
The same permissions and plan limits apply in the app and through your key.
The reference lists the operations that are live.
One call gives your agent the whole picture: GET /api/v1/context.
Every change can be previewed and is logged for your team. Reversible stage moves, assignments, dismissals and checklist ticks can be undone for a short time.
Your teammates see each change in the activity feed, marked via API. Limits keep every customer fast, and the headers tell your agent when to wait.
Send your key in Authorization: Bearer $VICTAVIO_API_KEY or the X-API-Key header. A key belongs to one workspace and works as the person who made it, with that person's current role.
Choose Read or Read and write. AI operations also need write access because they use your workspace's AI allowance. Cookies do not authorize API calls.
| Plan | Active keys | Calls per minute | Calls per day |
|---|---|---|---|
| Pro | 5 | 120 | 10,000 |
| Team | 20 | 300 | 30,000 |
Each key has a limit of 60 units per minute. Some operations use more than one unit. Promo trials allow 2,000 calls per day. Quotas reset at 00:00 UTC.
A 429 response includes Retry-After. Wait that long and try again. Read RateLimit-Remaining and X-Victavio-Daily-Remaining to pace calls.
| Status | Code | Next step |
|---|---|---|
| 400 | validation | Check the fields in the reference. |
| 401 | unauthenticated | Check that the key is active and in a header. |
| 402 | plan_limit | Check the plan and its limits. |
| 403 | permission_denied | Check the key scope and your role. |
| 404 | not_found | Read the record in the connected workspace. |
| 409 | version_conflict | Read the current version before retrying. |
| 429 | rate_limited | Wait for Retry-After. |
| 503 | maintenance | Wait for Retry-After. |
| 501 | not_implemented | This operation is coming soon. |
List calls accept limit and cursor. Pass next_cursor back with the same filters to read the next page. A page holds up to 50 rows.
Use fields=id,title,due.at_iso,fit to keep the response small. The id stays. GET responses include ETag. Send If-None-Match to receive 304 when the result is unchanged.
Send Idempotency-Key on a write. Repeating that key with the same input replays its result for 24 hours. An identical write without a key also has a short duplicate guard.
Use ?preview=true to review a write first. Your change log is in Settings, API and AI apps. Undo stops if the record changed after the API changed it.
Use If-Match with a pursuit's version when moving one stage. Bulk moves accept expected_version on each row. A failed row leaves earlier successful rows in place.
Keys are shown once and stored as keyed hashes. Rotate a key after any suspected exposure. Revoke it in Settings to stop access.
Secret scanners can match vic_(live|test)_[0-9A-Za-z]{36}. Never put a key in a URL or public code.
API access is paused. Revoke an exposed key in Settings or contact support.
API v1 and MCP are being prepared for launch. The reference includes only registered operations with output schemas. ChatGPT and Claude OAuth connections are coming soon.
No. It comes with Pro and Team, within the limits above.
No. Victavio never submits, signs, registers or contacts a buyer, and the API has no way to.
Only when you call an AI operation. It then uses your workspace's monthly AI allowance.
No. Upgrade to Pro or Team to create keys.
Revoke it in Settings. Contact support if you found a key that belongs to someone else.