> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtualityhub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Trigger V-Run Python workflows programmatically via HTTPS from your backend, CI/CD, webhooks, or n8n — with per-workflow API keys and JSON input payloads.

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.

```bash theme={null}
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](/api-reference/authentication) for details.

## Available endpoints

<CardGroup cols={2}>
  <Card title="Execute workflow" icon="play" href="/api-reference/trigger-workflow">
    Execute a published workflow with input parameters.
  </Card>
</CardGroup>

## 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:

```json theme={null}
{
  "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](mailto:sales@virtualityhub.com).