API Documentation

The VirtuousAI API is organized around REST principles with predictable resource-oriented URLs, standard HTTP methods, and JSON responses.

Base URL

https://vai-dev.virtuousai.com/api/v1

http://localhost:8000/api/v1

Authentication

Required

All API requests require authentication via API key or OAuth2 access token.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://vai-dev.virtuousai.com/api/v1/connections

Core Primitives

VirtuousAI is built around four core primitives. Understanding these concepts is key to using the API effectively.

Templates

Global blueprints that define action and connection configurations

Connections

Securely store credentials for external services like Salesforce, HubSpot, and databases

Actions

Discrete units of work that can be executed, monitored, and composed into workflows

Automations

Event-driven workflows that trigger actions based on schedules or external events

OpenAPI Reference

For detailed endpoint documentation with request/response schemas, see the OpenAPI Reference.

Authentication Endpoints

OAuth flows, device auth, and session management

Connection Endpoints

CRUD operations for external service credentials

Action Run Endpoints

Execute and monitor action instances

Automation Endpoints

Configure and trigger automated workflows

Response Format

All successful responses return JSON with consistent structure:

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "perPage": 20
  }
}

Error Handling

Errors follow RFC 7807 Problem Details format:

{
  "type": "https://vai-dev.virtuousai.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid parameters",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address"
    }
  ]
}

Status	Meaning
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing or invalid token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`422`	Unprocessable - Validation failed
`429`	Too Many Requests - Rate limited
`500`	Server Error - Something went wrong

Rate Limiting

API requests are rate limited per organization:

Plan	Requests/minute
Free	60
Pro	300
Enterprise	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640995200