API reference
API reference
The HTTP API behind Cloud, Git, Chat, Knowledge, Mail and the admin app, generated from its source.
The platform API at https://api.dev.gov.vin is the API the platform's own apps and the command line use. Every route, scope, field, response and error on these pages is read from the API's source at build time, so the reference matches the deployed code.
For scripts, the command line with an API key (SI_TOKEN) is the simplest; AI clients use the MCP server with an MCP key. Git takes any key with the right git scope.
Authentication
Send a bearer token:
Authorization: Bearer <token>| Caller | Token | Scopes checked |
|---|---|---|
| A signed-in person | An access token that id.dev.gov.vin issued to one of the platform's apps (Cloud, Chat, Git, Knowledge, Mail, admin) or the command line. | The person's role in the organization in the path. |
| An API key | An si_api_ key (Keys). | The key's own scopes, in its own organization. |
| A platform agent key | An si_agent_ key. Platform organization only. | The key's own scopes, in its own organization. |
| A self-hosted agent | Its device token (si_dev_), on the agent device endpoints only. | None; the device acts only on its own jobs. |
GET /health is the only route without authentication. A missing, expired or unknown token gets 401 Unauthorized; a missing scope gets 403 with Missing scope <scope>.
Requests and responses
- Organization routes start with
/v1/orgs/:orgId, the organization id (org_…), not its slug. - Request and response bodies are JSON. Field tables list each field's type, whether it's required, its default and its validation.
- A body or query string that fails validation gets
400with the validation issues. - Errors are
{ "error": "<message>" }with the status in each route's Errors table. Anything unexpected is500 Internal error. - Lists that page return a
cursor; pass it back to get the next page. Nocursormeans the last page.
AWS errors
Database and storage routes call DynamoDB and S3 directly. Their errors map to API errors as follows; routes that do this say so.
| AWS error | Status | Message |
|---|---|---|
ValidationException, InvalidArgument, InvalidRequest, MalformedXML, SerializationException | 400 | AWS's message, or "AWS rejected the request." |
ConditionalCheckFailedException | 409 | The item changed since it was read. Reload and try again. |
TransactionCanceledException | 409 | An item with the new key already exists, or the original was changed or deleted. |
ResourceNotFoundException, NoSuchBucket, NoSuchKey, NotFound | 404 | "File not found." or "Not found in AWS. It may have been deleted outside the platform." |
ResourceInUseException, LimitExceededException, OperationAborted, BucketNotEmpty, IndexNotFoundException, ContinuousBackupsUnavailableException | 409 | AWS's message, or "The resource is busy. Try again shortly." |
ProvisionedThroughputExceededException, ThrottlingException, RequestLimitExceeded, SlowDown | 429 | AWS is throttling requests. Try again in a moment. |
| Any other | 502 | AWS request failed. Try again. |
Routes
| Page | Routes |
|---|---|
| Health, identity and locations | GET /health, GET /v1/me, GET /v1/locations |
| Organizations and members | GET /v1/orgs/:orgId/members, GET /v1/orgs/:orgId, PATCH /v1/orgs/:orgId, GET /v1/orgs/:orgId/contents, DELETE /v1/orgs/:orgId |
| Projects | GET /v1/orgs/:orgId/projects, POST /v1/orgs/:orgId/projects, GET /v1/orgs/:orgId/projects/:projectId, PATCH /v1/orgs/:orgId/projects/:projectId, POST /v1/orgs/:orgId/projects/:projectId/transfer, DELETE /v1/orgs/:orgId/projects/:projectId |
| Environment variables | GET /v1/orgs/:orgId/projects/:projectId/env, POST /v1/orgs/:orgId/projects/:projectId/env, PUT /v1/orgs/:orgId/projects/:projectId/env/:key, DELETE /v1/orgs/:orgId/projects/:projectId/env/:key |
| Sign-in clients | GET /v1/orgs/:orgId/projects/:projectId/oauth-clients, POST /v1/orgs/:orgId/projects/:projectId/oauth-clients, PATCH /v1/orgs/:orgId/projects/:projectId/oauth-clients/:clientId, POST /v1/orgs/:orgId/projects/:projectId/oauth-clients/:clientId/secret, DELETE /v1/orgs/:orgId/projects/:projectId/oauth-clients/:clientId |
| Deployments | POST /v1/orgs/:orgId/projects/:projectId/uploads, POST /v1/orgs/:orgId/projects/:projectId/deployments, GET /v1/orgs/:orgId/deployments/:deploymentId/build-log, GET /v1/orgs/:orgId/deployments/:deploymentId/runtime-logs/tail, GET /v1/orgs/:orgId/deployments, GET /v1/orgs/:orgId/deployments/:deploymentId, GET /v1/orgs/:orgId/deployments/:deploymentId/logs, GET /v1/orgs/:orgId/deployments/:deploymentId/runtime-logs, POST /v1/orgs/:orgId/deployments/:deploymentId/redeploy, POST /v1/orgs/:orgId/deployments/:deploymentId/promote |
| Domains | GET /v1/orgs/:orgId/domains, POST /v1/orgs/:orgId/domains, POST /v1/orgs/:orgId/domains/:hostname/verify, POST /v1/orgs/:orgId/domains/:hostname/cloudflare, PATCH /v1/orgs/:orgId/domains/:hostname, DELETE /v1/orgs/:orgId/domains/:hostname, GET /v1/orgs/:orgId/integrations/cloudflare, POST /v1/orgs/:orgId/integrations/cloudflare/authorize, POST /v1/orgs/:orgId/integrations/cloudflare/oauth, PUT /v1/orgs/:orgId/integrations/cloudflare, DELETE /v1/orgs/:orgId/integrations/cloudflare |
| Repositories, databases and buckets | GET /v1/orgs/:orgId/resources, POST /v1/orgs/:orgId/resources, PATCH /v1/orgs/:orgId/resources/:type/:resourceId, DELETE /v1/orgs/:orgId/resources/:type/:resourceId |
| Databases | GET /v1/orgs/:orgId/databases, GET /v1/orgs/:orgId/databases/:resourceId, POST /v1/orgs/:orgId/databases/:resourceId/scan, POST /v1/orgs/:orgId/databases/:resourceId/query, POST /v1/orgs/:orgId/databases/:resourceId/items/get, PUT /v1/orgs/:orgId/databases/:resourceId/items, POST /v1/orgs/:orgId/databases/:resourceId/items/delete, POST /v1/orgs/:orgId/databases/:resourceId/indexes, DELETE /v1/orgs/:orgId/databases/:resourceId/indexes/:indexName, GET /v1/orgs/:orgId/databases/:resourceId/metrics, GET /v1/orgs/:orgId/databases/:resourceId/settings, PATCH /v1/orgs/:orgId/databases/:resourceId/settings, PATCH /v1/orgs/:orgId/databases/:resourceId/tags, DELETE /v1/orgs/:orgId/databases/:resourceId |
| Storage | GET /v1/orgs/:orgId/storage, GET /v1/orgs/:orgId/storage/:resourceId, GET /v1/orgs/:orgId/storage/:resourceId/objects, GET /v1/orgs/:orgId/storage/:resourceId/object, GET /v1/orgs/:orgId/storage/:resourceId/download, POST /v1/orgs/:orgId/storage/:resourceId/uploads, POST /v1/orgs/:orgId/storage/:resourceId/folders, POST /v1/orgs/:orgId/storage/:resourceId/objects/delete, GET /v1/orgs/:orgId/storage/:resourceId/settings, PUT /v1/orgs/:orgId/storage/:resourceId/cors, PUT /v1/orgs/:orgId/storage/:resourceId/versioning, POST /v1/orgs/:orgId/storage/:resourceId/lifecycle, DELETE /v1/orgs/:orgId/storage/:resourceId/lifecycle/:ruleId, DELETE /v1/orgs/:orgId/storage/:resourceId |
| Repositories | GET /v1/orgs/:orgId/git-credentials, POST /v1/orgs/:orgId/git-credentials, DELETE /v1/orgs/:orgId/git-credentials/:keyId, GET /v1/orgs/:orgId/repos/:name/branches, GET /v1/orgs/:orgId/repos/:name/branches/divergence, POST /v1/orgs/:orgId/repos/:name/branches, DELETE /v1/orgs/:orgId/repos/:name/branches, GET /v1/orgs/:orgId/repos/:name/tags, POST /v1/orgs/:orgId/repos/:name/contents, POST /v1/orgs/:orgId/repos/:name/contents/uploads, POST /v1/orgs/:orgId/repos/:name/contents/archive, GET /v1/orgs/:orgId/repos/:name/contents/raw, GET /v1/orgs/:orgId/repos/:name/contents/files, POST /v1/orgs/:orgId/repos/:name/contents/blobs, GET /v1/orgs/:orgId/repos/:name/compare, GET /v1/orgs/:orgId/repos/:name/labels, PUT /v1/orgs/:orgId/repos/:name/labels, DELETE /v1/orgs/:orgId/repos/:name/labels, GET /v1/orgs/:orgId/repos, GET /v1/orgs/:orgId/repos/-/available, GET /v1/orgs/:orgId/repos/-/people, POST /v1/orgs/:orgId/repos, POST /v1/orgs/:orgId/repos/:name/rename, DELETE /v1/orgs/:orgId/repos/:name, GET /v1/orgs/:orgId/repos/:name/protection, PUT /v1/orgs/:orgId/repos/:name/protection, GET /v1/orgs/:orgId/repos/:name, PATCH /v1/orgs/:orgId/repos/:name, GET /v1/orgs/:orgId/repos/:name/tree, GET /v1/orgs/:orgId/repos/:name/blob, GET /v1/orgs/:orgId/repos/:name/commits, GET /v1/orgs/:orgId/repos/:name/last-commits, GET /v1/orgs/:orgId/repos/:name/last-commit, GET /v1/orgs/:orgId/repos/:name/commits/:sha, GET /v1/orgs/:orgId/repos/:name/insights |
| Issues | GET /v1/orgs/:orgId/repos/:name/issues, POST /v1/orgs/:orgId/repos/:name/issues, GET /v1/orgs/:orgId/repos/:name/issues/:number, PATCH /v1/orgs/:orgId/repos/:name/issues/:number, POST /v1/orgs/:orgId/repos/:name/issues/:number/comments |
| Pull requests | GET /v1/orgs/:orgId/repos/:name/pulls/:number/review, POST /v1/orgs/:orgId/repos/:name/pulls/:number/review/comments, POST /v1/orgs/:orgId/repos/:name/pulls/:number/approval, POST /v1/orgs/:orgId/repos/:name/pulls/:number/reopen, GET /v1/orgs/:orgId/repos/:name/pulls, POST /v1/orgs/:orgId/repos/:name/pulls, GET /v1/orgs/:orgId/repos/:name/pulls/:number, PATCH /v1/orgs/:orgId/repos/:name/pulls/:number, GET /v1/orgs/:orgId/repos/:name/pulls/:number/commits, GET /v1/orgs/:orgId/repos/:name/pulls/:number/files, POST /v1/orgs/:orgId/repos/:name/pulls/:number/merge, POST /v1/orgs/:orgId/repos/:name/pulls/:number/close, POST /v1/orgs/:orgId/repos/:name/pulls/:number/comments |
| Agents | GET /v1/orgs/:orgId/agents, PATCH /v1/orgs/:orgId/agents/devices/:deviceId, DELETE /v1/orgs/:orgId/agents/devices/:deviceId, POST /v1/orgs/:orgId/agents/requests/:deviceId/:host/:decision, POST /v1/orgs/:orgId/agents/jobs, GET /v1/orgs/:orgId/agents/jobs/:jobId, POST /v1/orgs/:orgId/agents/jobs/:jobId/cancel, POST /v1/orgs/:orgId/agents/jobs/:jobId/request-access |
| Agent device endpoints | POST /v1/agent/poll, POST /v1/agent/jobs/:jobId/complete, POST /v1/agent/jobs/:jobId/heartbeat, POST /v1/agent/jobs/:jobId/upload-url, POST /v1/agent/network-requests |
| Connectors | GET /v1/orgs/:orgId/connectors, GET /v1/orgs/:orgId/connectors/:connectorId, POST /v1/orgs/:orgId/connectors, POST /v1/orgs/:orgId/connectors/:connectorId/test, PATCH /v1/orgs/:orgId/connectors/:connectorId, DELETE /v1/orgs/:orgId/connectors/:connectorId, POST /v1/orgs/:orgId/connectors/:connectorId/oauth/start, POST /v1/orgs/:orgId/connectors/oauth/callback |
| Knowledge pages | GET /v1/orgs/:orgId/pages, POST /v1/orgs/:orgId/pages, GET /v1/orgs/:orgId/pages/search, GET /v1/orgs/:orgId/pages/:pageId, PATCH /v1/orgs/:orgId/pages/:pageId, PUT /v1/orgs/:orgId/pages/:pageId/content, DELETE /v1/orgs/:orgId/pages/:pageId, GET /v1/orgs/:orgId/favorites, PUT /v1/orgs/:orgId/favorites/:pageId, DELETE /v1/orgs/:orgId/favorites/:pageId |
GET /v1/orgs/:orgId/mail/mailboxes, PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/settings, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/limits, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/actions, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/body, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/attachments/:index, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/raw, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/uploads, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/send, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/recipients/check, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId, PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId, DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels, DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels/:labelId | |
| Mail administration | GET /v1/orgs/:orgId/mail/domains, POST /v1/orgs/:orgId/mail/domains, POST /v1/orgs/:orgId/mail/domains/:domain/verify, PATCH /v1/orgs/:orgId/mail/domains/:domain, DELETE /v1/orgs/:orgId/mail/domains/:domain, GET /v1/orgs/:orgId/mail/members, GET /v1/orgs/:orgId/mail/admin/mailboxes, POST /v1/orgs/:orgId/mail/admin/mailboxes, PATCH /v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId, DELETE /v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId, POST /v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId/aliases, DELETE /v1/orgs/:orgId/mail/admin/aliases/:address, GET /v1/orgs/:orgId/mail/usage |
| Calendar | GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars, PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId, DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/events, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId, PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId, DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId/respond, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/import, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/export |
| Contacts | GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books, PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId, DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId, PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId, DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo, PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo, DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo, POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/import, GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/export |
| Analytics | GET /v1/orgs/:orgId/analytics |
| Audit log | GET /v1/orgs/:orgId/audit, GET /v1/orgs/:orgId/audit/export, PUT /v1/orgs/:orgId/audit/export |
| Platform administration | GET /v1/platform/analytics, GET /v1/platform/mail/usage, GET /v1/platform/usage, GET /v1/platform/orgs, POST /v1/platform/orgs, PATCH /v1/platform/orgs/:orgId, GET /v1/platform/stats, GET /v1/platform/audit, GET /v1/platform/regions, PUT /v1/platform/regions/:regionId, PUT /v1/platform/locations/:locationId, GET /v1/platform/plans, PUT /v1/platform/plans/:planId, GET /v1/platform/models, PUT /v1/platform/models/:modelId |