Skip to main content

API Reference

Complete reference documentation for the Vantage REST API. All endpoints require authentication via API key or OAuth token.

Base URL​

https://api.vantage.omnivector.solutions/v1

Authentication​

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Jobs API​

Manage computational jobs on your clusters.

List Jobs​

GET /jobs

Query parameters:

  • limit (integer) - Number of jobs to return (default: 50, max: 100)
  • offset (integer) - Number of jobs to skip (default: 0)
  • status (string) - Filter by job status
  • cluster_id (string) - Filter by cluster ID
  • user_id (string) - Filter by user ID

Example request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.vantage.omnivector.solutions/v1/jobs?limit=10&status=running"

Example response:

{
  "jobs": [
    {
      "id": "job_123",
      "name": "simulation-run-1",
      "status": "running",
      "cluster_id": "cluster_abc",
      "user_id": "user_456",
      "command": "python simulate.py",
      "resources": {
        "cpus": 4,
        "memory": "8GB",
        "gpus": 1
      },
      "created_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:31:00Z",
      "completed_at": null
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10
}

Create Job​

POST /jobs

Request body:

{
  "name": "job-name",
  "cluster_id": "cluster_123",
  "command": "python script.py",
  "resources": {
    "cpus": 2,
    "memory": "4GB",
    "gpus": 0
  },
  "environment": {
    "ENV_VAR": "value"
  },
  "working_directory": "/home/user",
  "output_path": "/outputs/"
}

Get Job​

GET /jobs/{job_id}

Update Job​

PATCH /jobs/{job_id}

Delete Job​

DELETE /jobs/{job_id}

Get Job Output​

GET /jobs/{job_id}/output

Get Job Logs​

GET /jobs/{job_id}/logs

Clusters API​

Manage compute clusters.

List Clusters​

GET /clusters

Get Cluster​

GET /clusters/{cluster_id}

Get Cluster Usage​

GET /clusters/{cluster_id}/usage

Get Cluster Nodes​

GET /clusters/{cluster_id}/nodes

Storage API​

Manage files and data.

List Files​

GET /storage/files

Upload File​

POST /storage/files

Content-Type: multipart/form-data

Form fields:

  • file - The file to upload
  • path - Destination path
  • overwrite - Whether to overwrite existing files (default: false)

Download File​

GET /storage/files/{file_id}/download

Delete File​

DELETE /storage/files/{file_id}

Get File Metadata​

GET /storage/files/{file_id}

Teams API​

Manage team membership and permissions.

List Teams​

GET /teams

Get Team​

GET /teams/{team_id}

List Team Members​

GET /teams/{team_id}/members

Add Team Member​

POST /teams/{team_id}/members

Remove Team Member​

DELETE /teams/{team_id}/members/{user_id}

Users API​

Manage user accounts and profiles.

Get Current User​

GET /users/me

Update User Profile​

PATCH /users/me

List User Jobs​

GET /users/{user_id}/jobs

Billing API​

Access billing and usage information.

Get Usage Summary​

GET /billing/usage

Get Invoices​

GET /billing/invoices

Get Invoice​

GET /billing/invoices/{invoice_id}

Monitoring API​

Retrieve metrics and monitoring data.

Get Job Metrics​

GET /monitoring/jobs/{job_id}/metrics

Get Cluster Metrics​

GET /monitoring/clusters/{cluster_id}/metrics

Webhooks API​

Manage webhook subscriptions for events.

List Webhooks​

GET /webhooks

Create Webhook​

POST /webhooks

Update Webhook​

PATCH /webhooks/{webhook_id}

Delete Webhook​

DELETE /webhooks/{webhook_id}

Common Parameters​

Pagination​

Most list endpoints support pagination:

  • limit - Number of items per page (default: 50, max: 100)
  • offset - Number of items to skip
  • page - Page number (alternative to offset)

Filtering​

Many endpoints support filtering:

  • created_after - ISO 8601 timestamp
  • created_before - ISO 8601 timestamp
  • updated_after - ISO 8601 timestamp
  • updated_before - ISO 8601 timestamp

Sorting​

Use the sort parameter:

  • created_at - Sort by creation date
  • updated_at - Sort by update date
  • name - Sort alphabetically
  • Add - prefix for descending order (e.g., -created_at)

Error Responses​

All error responses follow this format:

{
  "error": "error_code",
  "message": "Human readable error message",
  "details": {
    "field": "field_name",
    "code": "validation_error"
  },
  "request_id": "req_123456789"
}

Common Error Codes​

  • validation_error - Request validation failed
  • authentication_failed - Invalid or missing credentials
  • permission_denied - Insufficient permissions
  • resource_not_found - Requested resource doesn't exist
  • rate_limit_exceeded - Too many requests
  • internal_error - Server error

Response Headers​

All responses include these headers:

X-Request-ID: req_123456789
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642262400
Content-Type: application/json

SDKs and Libraries​

Official SDKs are available for:

OpenAPI Specification​

Download the complete OpenAPI 3.0 specification:

Postman Collection​

Import our Postman collection for easy API testing: