API overview

The V-Run API lets you trigger published workflows from your own applications, CI/CD pipelines, or external services.

Base URL

https://run.virtualityhub.com/api

Authentication

All API requests require an API key passed in the x-api-key header. Each workflow has its own unique API key, available in the API Trigger tab of the workflow editor.

curl -X POST https://run.virtualityhub.com/api/workflows/{workflowId}/execute \
  -H "x-api-key: YOUR_WORKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

See Authentication for details.

Available endpoints

Execute workflow

Execute a published workflow with input parameters.

Request format

Content-Type: application/json or multipart/form-data (when uploading files)
Body: JSON object mapping input parameter names to values, matching the workflow’s config.yaml input schema

Response format

All responses are JSON. A successful execution returns the run result:

{
  "status": "success",
  "executionId": "exec_abc123",
  "outputs": {
    "results": "https://run.virtualityhub.com/api/run-logs/exec_abc123/files/output.json"
  }
}

Error handling

Status code	Description
`200`	Workflow executed successfully.
`400`	Invalid request — missing or malformed input parameters.
`401`	Unauthorized — missing or invalid API key.
`402`	Insufficient credits — top up your account to continue.
`404`	Workflow not found or has no committed version.
`500`	Internal server error.

Rate limits

API executions are subject to fair-use rate limits. If you need higher throughput, contact sales@virtualityhub.com.

Overview

Endpoints

Base URL

Authentication

Available endpoints

Execute workflow

Request format

Response format

Error handling

Rate limits

​Base URL

​Authentication

​Available endpoints

Execute workflow

​Request format

​Response format

​Error handling

​Rate limits

Base URL

Authentication

Available endpoints

Request format

Response format

Error handling

Rate limits