VM0API Overview
Introduction to the VM0 Public API v1
The VM0 Public API allows you to programmatically manage agents, execute runs, and work with storage resources.
Base URL
All API requests should be made to:
https://api.vm0.ai/v1/Resources
Agents
List and retrieve agent information
Artifacts
Access output files from agent runs
Runs
Execute agents and monitor run status
Volumes
Manage input storage for agents
Authentication
All API requests require authentication using a Bearer token in the Authorization header.
Token Format
API tokens follow this format:
vm0_live_<64 hex characters>Using the Token
Include your token in the Authorization header with the Bearer prefix:
curl https://api.vm0.ai/v1/agents \
-H "Authorization: Bearer vm0_live_xxx"Obtaining a Token
Via CLI
The easiest way to get a token is through the VM0 CLI:
vm0 auth loginThis creates a token and stores it in your local configuration. To view your token:
vm0 auth setup-tokenToken Security
Keep your API tokens secure. Never commit them to version control or share them publicly.
Best practices:
- Store tokens in environment variables
- Use short expiration times for automated systems
- Rotate tokens regularly
- Revoke tokens immediately if compromised
Errors
The API uses standard HTTP status codes and returns structured error responses.
Error Response Format
{
"error": {
"type": "invalid_request_error",
"code": "resource_not_found",
"message": "No such agent: 'my-agent'"
}
}| Field | Type | Description |
|---|---|---|
type | string | Category of the error |
code | string | Specific error code |
message | string | Human-readable error description |
Error Types
| Type | HTTP Status | Description |
|---|---|---|
authentication_error | 401 | Authentication failed |
invalid_request_error | 400 | Invalid parameters or request body |
not_found_error | 404 | Requested resource doesn't exist |
conflict_error | 409 | Resource conflict (e.g., duplicate name) |
api_error | 500 | Internal server error |
Error Codes
Authentication Errors (401)
| Code | Description |
|---|---|
invalid_api_key | API key is missing, malformed, expired, or revoked |
Request Errors (400)
| Code | Description |
|---|---|
invalid_parameter | A parameter value is invalid |
missing_parameter | A required parameter is missing |
invalid_state | Resource is in an invalid state for the requested operation |
Resource Errors (404, 409)
| Code | Description |
|---|---|
resource_not_found | The requested resource doesn't exist |
resource_already_exists | A resource with this name already exists |
Pagination
List endpoints use cursor-based pagination to efficiently handle large result sets.
Response Format
Paginated responses include a pagination object:
{
"data": [
{ "id": "ag_abc", "name": "agent-1" },
{ "id": "ag_def", "name": "agent-2" }
],
"pagination": {
"hasMore": true,
"nextCursor": "eyJpZCI6ImFnX2RlZiJ9"
}
}| Field | Type | Description |
|---|---|---|
hasMore | boolean | Whether more results exist |
nextCursor | string | Cursor for the next page (null if no more results) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Number of items per page (1-100) |
cursor | string | - | Cursor from previous response |
Usage
Request the first page without a cursor:
curl "https://api.vm0.ai/v1/agents?limit=10" \
-H "Authorization: Bearer vm0_live_xxx"Use the nextCursor from the previous response for subsequent pages:
curl "https://api.vm0.ai/v1/agents?limit=10&cursor=eyJpZCI6ImFnX2RlZiJ9" \
-H "Authorization: Bearer vm0_live_xxx"Response Headers
Every response includes these headers:
| Header | Description |
|---|---|
X-Request-Id | Unique request identifier for debugging |
X-API-Version | API version (currently v1) |