VersionOps API Reference

Complete API documentation for integrating with VersionOps. All endpoints return JSON and use standard HTTP response codes.

Authentication

VersionOps uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header for all authenticated requests.

Authorization Header

HTTP

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Login

POST/api/auth/login

Authenticate user and receive access token.

No Auth

Request Body

JSON

{
  "username": "[email protected]",
  "password": "password"
}

Response

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Service Token Authentication

For agent and machine-to-machine authentication, use service tokens. Create service tokens in Dashboard Settings.

HTTP

Authorization: Bearer vops_agent_abc123...

Token Expiration

Access tokens expire after 24 hours. Refresh by calling the login endpoint again. Service tokens do not expire unless manually revoked.

Public Endpoints

These endpoints do not require authentication.

GET/api/public/plans

Returns list of active subscription plans.

No Auth

Response

JSON

{
  "items": [
    {
      "id": "free",
      "name": "Free",
      "price": 0,
      "features": ["basic_inventory", "up_to_5_hosts"]
    },
    {
      "id": "pro",
      "name": "Professional",
      "price": 29,
      "features": ["unlimited_hosts", "cve_scanning", "notifications"]
    }
  ]
}

GET/api/public/features

Returns list of available features.

No Auth

Response

JSON

{
  "items": [
    {
      "id": "cve_scanning",
      "name": "CVE Scanning",
      "description": "Automatic vulnerability detection"
    }
  ]
}

GET/api/config

Returns public system configuration (LDAP enabled, SaaS mode, etc).

No Auth

Response

JSON

{
  "saas_enabled": true,
  "ldap_enabled": false,
  "registration_enabled": true
}

User Endpoints

All user endpoints require a valid JWT token in the Authorization header.

GET/api/user/info

Returns current authenticated user information.

Auth Required

Response

JSON

{
  "id": "user_123",
  "email": "[email protected]",
  "name": "John Doe",
  "organization_id": "org_456",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}

GET/api/user/features

Returns features available to current user based on their subscription plan.

Auth Required

Response

JSON

{
  "features": [
    "basic_inventory",
    "cve_scanning",
    "notifications",
    "smart_recommendations"
  ]
}

Hosts

Manage and monitor hosts in your infrastructure.

GET/api/hosts

List all hosts in your organization.

Auth Required

Parameters

Name	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`search`	string	Search by hostname or IP

Response

JSON

{
  "items": [
    {
      "id": "host_123",
      "hostname": "server-01",
      "ip_address": "192.168.1.10",
      "os": "Ubuntu 22.04",
      "last_seen": "2024-01-20T15:30:00Z",
      "agent_version": "1.0.5"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

GET/api/hosts/{host_id}

Get detailed information about a specific host.

Auth Required

Parameters

Name	Type	Description
`host_id`	string	Host ID

Response

JSON

{
  "id": "host_123",
  "hostname": "server-01",
  "ip_address": "192.168.1.10",
  "os": "Ubuntu 22.04",
  "kernel": "5.15.0-generic",
  "last_seen": "2024-01-20T15:30:00Z",
  "agent_version": "1.0.5",
  "applications_count": 15
}

POST/api/hosts

Manually create a new host entry.

Auth Required

Request Body

JSON

{
  "hostname": "server-01",
  "ip_address": "192.168.1.10",
  "os": "Ubuntu 22.04"
}

Response

JSON

{
  "id": "host_123",
  "hostname": "server-01",
  "ip_address": "192.168.1.10",
  "os": "Ubuntu 22.04",
  "created_at": "2024-01-20T15:30:00Z"
}

PUT/api/hosts/{host_id}

Update host information.

Auth Required

Parameters

Name	Type	Description
`host_id`	string	Host ID

Request Body

JSON

{
  "hostname": "server-01-updated",
  "ip_address": "192.168.1.11"
}

DELETE/api/hosts/{host_id}

Delete a host and all its associated data.

Auth Required

Parameters

Name	Type	Description
`host_id`	string	Host ID

Applications

Track software applications and versions across your infrastructure.

GET/api/applications

List all detected applications.

Auth Required

Response

JSON

{
  "items": [
    {
      "name": "nginx",
      "hosts_count": 12,
      "versions": ["1.24.0", "1.23.4"],
      "latest_version": "1.25.3"
    },
    {
      "name": "postgresql",
      "hosts_count": 5,
      "versions": ["15.2", "14.8"],
      "latest_version": "16.1"
    }
  ]
}

GET/api/applications/{name}

Get detailed information about a specific application.

Auth Required

Parameters

Name	Type	Description
`name`	string	Application name

Response

JSON

{
  "name": "nginx",
  "description": "High-performance web server",
  "hosts": [
    {
      "host_id": "host_123",
      "hostname": "web-01",
      "version": "1.24.0"
    }
  ],
  "latest_version": "1.25.3",
  "versions_distribution": {
    "1.24.0": 8,
    "1.23.4": 4
  }
}

GET/api/applications/{name}/stats

Get version distribution statistics for an application.

Auth Required

Parameters

Name	Type	Description
`name`	string	Application name

Response

JSON

{
  "name": "nginx",
  "total_hosts": 12,
  "versions": {
    "1.24.0": { "count": 8, "percentage": 66.7 },
    "1.23.4": { "count": 4, "percentage": 33.3 }
  },
  "outdated_hosts": 4
}

GET/api/applications/{name}/version-recommendationssmart_recommendations

Get smart version upgrade recommendations.

Auth Required

Parameters

Name	Type	Description
`name`	string	Application name

Response

JSON

{
  "name": "nginx",
  "current_version": "1.23.4",
  "recommendations": {
    "patch": "1.23.5",
    "minor": "1.24.0",
    "major": "1.25.3"
  },
  "security_updates": true
}

GET/api/applications/{name}/vulnerabilitiescve_scanning

Get known vulnerabilities (CVEs) for an application.

Auth Required

Parameters

Name	Type	Description
`name`	string	Application name

Response

JSON

{
  "name": "nginx",
  "vulnerabilities": [
    {
      "cve_id": "CVE-2023-12345",
      "severity": "HIGH",
      "cvss_score": 8.1,
      "description": "Buffer overflow vulnerability",
      "affected_versions": ["< 1.24.0"],
      "fixed_version": "1.24.0"
    }
  ]
}

Projects (npm Monitoring)

Manage npm projects and scan dependencies for vulnerabilities. Projects allow you to track npm packages separately from host-based inventory.

GET/api/projects

List all projects in your organization.

Auth Required

Parameters

Name	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)

Response

JSON

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "my-frontend-app",
      "type": "npm",
      "description": "React frontend application",
      "dependencies_count": 156,
      "vulnerabilities": {
        "critical": 1,
        "high": 2,
        "medium": 0,
        "low": 0
      },
      "last_scan_at": "2024-01-20T15:30:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 5,
  "page": 1
}

POST/api/projects

Create a new project for npm dependency tracking.

Auth Required

Request Body

JSON

{
  "name": "my-frontend-app",
  "description": "React frontend application"
}

Response

JSON

{
  "id": "proj_abc123",
  "name": "my-frontend-app",
  "description": "React frontend application",
  "created_at": "2024-01-20T15:30:00Z"
}

POST/api/projects/import

Create a new project and import dependencies in one step. Ideal for importing package.json from a local file.

Auth Required

Request Body

JSON

{
  "name": "my-frontend-app",
  "type": "npm",
  "description": "React frontend application",
  "dependencies": [
    { "name": "react", "version": "^18.2.0", "is_dev": false },
    { "name": "lodash", "version": "^4.17.21", "is_dev": false },
    { "name": "jest", "version": "^29.0.0", "is_dev": true }
  ]
}

Response

JSON

{
  "id": "proj_abc123",
  "name": "my-frontend-app",
  "dependency_count": 3,
  "vulnerability_count": 0,
  "created_at": "2024-01-20T15:30:00Z"
}

GET/api/projects/{project_id}

Get detailed information about a specific project. Note: Dependencies are fetched separately via GET /api/projects/{id}/dependencies.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Response

JSON

{
  "id": "proj_abc123",
  "name": "my-frontend-app",
  "type": "npm",
  "description": "React frontend application",
  "source_url": "https://github.com/example/my-app",
  "branch": "main",
  "dependencies_count": 156,
  "vulnerabilities": {
    "critical": 1,
    "high": 2,
    "medium": 0,
    "low": 0,
    "total": 3
  },
  "last_scan_at": "2024-01-20T15:30:00Z",
  "created_at": "2024-01-01T00:00:00Z"
}

DELETE/api/projects/{project_id}

Delete a project and all its associated data.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Dependency Import

Recommended: include the lockfile

For accurate CVE matching, include your lockfile vialock_file_text (raw file contents) and lock_file_name(original filename — selects the parser). Supported:package-lock.json, yarn.lock v1, and yarn berry. Without a lockfile, versions are resolved against the npm registry and transitive dependencies are skipped.

POST/api/projects/{project_id}/import/package-json

Import dependencies from package.json file. Include package-lock.json for exact versions and transitive dependencies. The import runs in the background.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Request Body

JSON

{
  "package_json": {
    "name": "my-app",
    "version": "1.0.0",
    "dependencies": {
      "react": "^18.2.0",
      "lodash": "^4.17.20"
    },
    "devDependencies": {
      "jest": "^29.0.0"
    }
  },
  "lock_file_text": "<raw contents of package-lock.json or yarn.lock>",
  "lock_file_name": "package-lock.json"
}

Response

JSON

{
  "status": "importing",
  "job_id": "job_abc123",
  "message": "Import started in background"
}

POST/api/projects/{project_id}/update-dependencies

Re-import package files and refresh the dependency list. Used by the 'Update Dependencies' button in UI. Triggers a full re-import and CVE scan.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Request Body

JSON

{
  "package_json": {
    "name": "my-app",
    "version": "1.0.1",
    "dependencies": {
      "react": "^18.3.0",
      "lodash": "^4.17.21"
    }
  },
  "lock_file_text": "<raw contents of package-lock.json or yarn.lock>",
  "lock_file_name": "package-lock.json"
}

Response

JSON

{
  "status": "importing",
  "job_id": "job_xyz789",
  "message": "Dependency update started in background"
}

Dependencies Management

GET/api/projects/{project_id}/dependencies

List all dependencies in a project with version and vulnerability information.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID
`include_dev`	boolean	Include dev dependencies (default: true)
`vulnerable_only`	boolean	Only show vulnerable packages (default: false)
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 50)

Response

JSON

{
  "dependencies": [
    {
      "id": "dep_abc123",
      "package_name": "react",
      "declared_version": "^18.2.0",
      "resolved_version": "18.2.0",
      "latest_version": "18.2.0",
      "is_dev_dependency": false,
      "vulnerability_count": 0,
      "critical_count": 0,
      "high_count": 0
    }
  ],
  "total": 156,
  "page": 1
}

POST/api/projects/{project_id}/dependencies/add

Manually add a dependency to a project.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Request Body

JSON

{
  "package_name": "axios",
  "version": "1.6.0",
  "is_dev_dependency": false
}

Response

JSON

{
  "id": "dep_xyz789",
  "package_name": "axios",
  "declared_version": "1.6.0",
  "latest_version": "1.6.2",
  "vulnerability_count": 0
}

DELETE/api/projects/{project_id}/dependencies/{package_name}

Remove a dependency from a project.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID
`package_name`	string	Package name (URL encoded if contains special chars)

Response

JSON

{
  "message": "Dependency 'axios' removed"
}

Vulnerability Scanning

POST/api/projects/{project_id}/rescancve_scanning

Re-scan existing dependencies for new CVE vulnerabilities. Used by the 'Scan Now' button in UI.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Response

JSON

{
  "project_id": "proj_abc123",
  "scan_completed_at": "2024-01-20T15:30:00Z",
  "summary": {
    "total_dependencies": 156,
    "vulnerable_packages": 3,
    "critical_vulnerabilities": 1,
    "high_vulnerabilities": 2
  },
  "status": "warning"
}

POST/api/projects/{project_id}/scancve_scanning

Full CI/CD scan endpoint. Requires package.json payload. Used for automated scanning from CI/CD pipelines.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Request Body

JSON

{
  "project_name": "my-app",
  "package_json": {
    "name": "my-app",
    "dependencies": { "lodash": "^4.17.20" }
  },
  "package_lock": { ... },
  "build_number": "123",
  "commit_sha": "abc123",
  "branch": "main"
}

Response

JSON

{
  "project_id": "proj_abc123",
  "scan_completed_at": "2024-01-20T15:30:00Z",
  "build_number": "123",
  "commit_sha": "abc123",
  "summary": {
    "total_dependencies": 50,
    "vulnerable_packages": 2,
    "critical_vulnerabilities": 0,
    "high_vulnerabilities": 1
  },
  "status": "warning"
}

GET/api/projects/{project_id}/vulnerabilitiescve_scanning

Get list of vulnerabilities found in project dependencies.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID
`severity`	string	Filter by severity (LOW, MEDIUM, HIGH, CRITICAL)

Response

JSON

{
  "items": [
    {
      "id": "GHSA-xxxx-yyyy-zzzz",
      "source": "github_advisory",
      "severity": "HIGH",
      "cvss_score": 7.5,
      "package": "lodash",
      "affected_versions": "< 4.17.21",
      "installed_version": "4.17.20",
      "fixed_version": "4.17.21",
      "title": "Prototype Pollution in lodash",
      "description": "Lodash versions prior to 4.17.21 are vulnerable to prototype pollution..."
    }
  ],
  "total": 3
}

GET/api/projects/{project_id}/recommendationssmart_recommendations

Get semver-aware update recommendations for project dependencies.

Auth Required

Parameters

Name	Type	Description
`project_id`	string	Project ID

Response

JSON

{
  "items": [
    {
      "package": "lodash",
      "current_version": "4.17.20",
      "recommendations": {
        "patch": "4.17.21",
        "minor": null,
        "major": null
      },
      "has_security_fix": true,
      "changelog_url": "https://github.com/lodash/lodash/releases/tag/4.17.21"
    },
    {
      "package": "react",
      "current_version": "17.0.2",
      "recommendations": {
        "patch": "17.0.3",
        "minor": null,
        "major": "18.2.0"
      },
      "has_security_fix": false
    }
  ]
}

CI/CD Integration

CI/CD scans run asynchronously. POST /api/public/cicd/scan queues a scan job and returns a job_id; upload-only pipelines stop here. Pipelines that gate the build poll GET /api/public/cicd/jobs/{job_id}until status is completed, failed, orcancelled, then exit with exit_code(0 ok, 1 CRITICAL found, 2 scan error,3 cancelled).

POST/api/public/cicd/scan

Queue an async dependency scan from CI. Returns a job_id to poll. Use from GitHub Actions, GitLab CI, or Jenkins.

Auth Required

Request Body

JSON

{
  "project_name": "my-frontend-app",
  "package_json": {
    "name": "my-app",
    "dependencies": { "lodash": "^4.17.20" }
  },
  "lock_file_text": "<raw contents of package-lock.json or yarn.lock>",
  "lock_file_name": "package-lock.json",
  "commit_sha": "abc123...",
  "branch": "main"
}

Response

JSON

{
  "success": true,
  "job_id": "job_abc123",
  "project_id": "proj_abc123",
  "project_name": "my-frontend-app",
  "status": "queued",
  "poll_url": "/api/public/cicd/jobs/job_abc123"
}

GET/api/public/cicd/jobs/{job_id}

Poll a CI/CD scan job. Returns progress while running, then result + exit_code when terminal. exit_code: 0 = ok, 1 = CRITICAL found, 2 = scan error, 3 = cancelled.

Auth Required

Parameters

Name	Type	Description
`job_id`	string	Job ID returned by /api/public/cicd/scan

Response

JSON

{
  "job_id": "job_abc123",
  "status": "completed",
  "progress": { "total": 142, "processed": 142, "percent": 100 },
  "exit_code": 1,
  "result": {
    "vulnerabilities": {
      "critical": 1,
      "high": 2,
      "medium": 4,
      "low": 7
    },
    "details": [
      {
        "id": "GHSA-xxxx-yyyy-zzzz",
        "severity": "CRITICAL",
        "package": "lodash",
        "fixed_version": "4.17.21"
      }
    ]
  }
}

Security Scanning (Trivy)

Scan container images, Infrastructure as Code files, and Kubernetes manifests for vulnerabilities and misconfigurations. Powered by Trivy.

GET/api/trivy/health

Check Trivy scanner health and availability.

Auth Required

Response

JSON

{
  "status": "healthy",
  "trivy_version": "0.50.0",
  "db_updated_at": "2026-03-25T12:00:00Z"
}

Container Image Scanning

POST/api/trivy/scan/containercontainer_scanning

Scan a container image for vulnerabilities. For private images, matching registry credentials are applied automatically.

Auth Required

Request Body

JSON

{
  "image": "nginx:1.25",
  "severity": "CRITICAL,HIGH,MEDIUM"
}

Response

JSON

{
  "scan_id": "scan_abc123",
  "status": "completed",
  "image": "nginx:1.25",
  "scan_type": "container",
  "summary": {
    "critical": 2,
    "high": 5,
    "medium": 12,
    "low": 8,
    "total": 27
  },
  "completed_at": "2026-03-26T10:30:00Z"
}

GET/api/trivy/scan/{scan_id}

Get detailed results of a specific scan.

Auth Required

Parameters

Name	Type	Description
`scan_id`	string	Scan ID

Response

JSON

{
  "scan_id": "scan_abc123",
  "status": "completed",
  "scan_type": "container",
  "image": "nginx:1.25",
  "summary": {
    "critical": 2,
    "high": 5,
    "medium": 12,
    "low": 8,
    "total": 27
  },
  "started_at": "2026-03-26T10:29:00Z",
  "completed_at": "2026-03-26T10:30:00Z"
}

GET/api/trivy/scan/{scan_id}/vulnerabilities

Get list of vulnerabilities found in a scan.

Auth Required

Parameters

Name	Type	Description
`scan_id`	string	Scan ID
`severity`	string	Filter by severity (CRITICAL, HIGH, MEDIUM, LOW)
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 50)

Response

JSON

{
  "vulnerabilities": [
    {
      "vulnerability_id": "CVE-2024-1234",
      "severity": "CRITICAL",
      "cvss_score": 9.8,
      "package_name": "openssl",
      "installed_version": "1.1.1k",
      "fixed_version": "1.1.1l",
      "title": "Buffer overflow in OpenSSL",
      "description": "A buffer overflow vulnerability...",
      "primary_url": "https://nvd.nist.gov/vuln/detail/CVE-2024-1234"
    }
  ],
  "total": 27,
  "page": 1
}

IaC and Kubernetes Scanning

POST/api/trivy/scan/iaccontainer_scanning

Scan Infrastructure as Code files for misconfigurations. Supports Terraform, CloudFormation, Dockerfiles, and Helm charts.

Auth Required

Request Body

JSON

{
  "content": "resource \"aws_s3_bucket\" \"data\" {\n  bucket = \"my-bucket\"\n}",
  "filename": "main.tf",
  "severity": "CRITICAL,HIGH,MEDIUM"
}

Response

JSON

{
  "scan_id": "scan_iac456",
  "status": "completed",
  "scan_type": "iac",
  "summary": {
    "critical": 0,
    "high": 2,
    "medium": 3,
    "low": 1,
    "total": 6
  },
  "completed_at": "2026-03-26T10:35:00Z"
}

POST/api/trivy/scan/kubernetescontainer_scanning

Scan Kubernetes manifests against CIS benchmarks and security best practices.

Auth Required

Request Body

JSON

{
  "content": "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-app\n...",
  "filename": "deployment.yaml",
  "severity": "CRITICAL,HIGH"
}

Response

JSON

{
  "scan_id": "scan_k8s789",
  "status": "completed",
  "scan_type": "kubernetes",
  "summary": {
    "critical": 1,
    "high": 3,
    "medium": 0,
    "low": 0,
    "total": 4
  },
  "completed_at": "2026-03-26T10:40:00Z"
}

Container Image Management

GET/api/trivy/images

List all tracked container images.

Auth Required

Parameters

Name	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)

Response

JSON

{
  "images": [
    {
      "id": "img_abc123",
      "image": "nginx:1.25",
      "auto_scan": true,
      "scan_interval_hours": 24,
      "last_scan_at": "2026-03-26T10:30:00Z",
      "vulnerability_summary": {
        "critical": 2,
        "high": 5,
        "medium": 12,
        "low": 8
      },
      "created_at": "2026-03-01T00:00:00Z"
    }
  ],
  "total": 5,
  "page": 1
}

POST/api/trivy/images

Add a container image to tracking. Optionally enable auto-scan.

Auth Required

Request Body

JSON

{
  "image": "nginx:1.25",
  "auto_scan": true,
  "scan_interval_hours": 24
}

Response

JSON

{
  "id": "img_abc123",
  "image": "nginx:1.25",
  "auto_scan": true,
  "scan_interval_hours": 24,
  "created_at": "2026-03-26T10:00:00Z"
}

Scan History & Analytics

GET/api/trivy/scans

Get scan history with filtering.

Auth Required

Parameters

Name	Type	Description
`scan_type`	string	Filter by type (container, iac, kubernetes)
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)

Response

JSON

{
  "scans": [
    {
      "scan_id": "scan_abc123",
      "scan_type": "container",
      "target": "nginx:1.25",
      "status": "completed",
      "summary": { "critical": 2, "high": 5, "medium": 12, "low": 8 },
      "completed_at": "2026-03-26T10:30:00Z"
    }
  ],
  "total": 50,
  "page": 1
}

GET/api/trivy/analytics/summary

Get aggregated vulnerability analytics and trends.

Auth Required

Parameters

Name	Type	Description
`days`	integer	Time range in days (7, 30, or 90, default: 30)

Response

JSON

{
  "total_scans": 150,
  "total_vulnerabilities": 342,
  "severity_breakdown": {
    "critical": 12,
    "high": 45,
    "medium": 156,
    "low": 129
  },
  "trends": {
    "critical": [
      { "date": "2026-03-20", "count": 15 },
      { "date": "2026-03-26", "count": 12 }
    ]
  },
  "top_vulnerable_images": [
    { "image": "node:18", "vulnerability_count": 45 }
  ]
}

Container Registries

Manage private container registry credentials for scanning private images. Credentials are encrypted at rest and masked in API responses.

GET/api/trivy/registries

List all configured container registries.

Auth Required

Response

JSON

{
  "registries": [
    {
      "id": "reg_abc123",
      "name": "Production ECR",
      "registry_type": "ecr",
      "url": "123456789.dkr.ecr.us-east-1.amazonaws.com",
      "status": "active",
      "last_tested_at": "2026-03-26T09:00:00Z",
      "created_at": "2026-03-01T00:00:00Z"
    }
  ],
  "total": 3
}

POST/api/trivy/registries

Add registry credentials. Credentials are encrypted at rest.

Auth Required

Request Body

JSON

{
  "name": "Production ECR",
  "registry_type": "ecr",
  "url": "123456789.dkr.ecr.us-east-1.amazonaws.com",
  "credentials": {
    "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "aws_region": "us-east-1"
  }
}

Response

JSON

{
  "id": "reg_abc123",
  "name": "Production ECR",
  "registry_type": "ecr",
  "url": "123456789.dkr.ecr.us-east-1.amazonaws.com",
  "status": "active",
  "created_at": "2026-03-26T10:00:00Z"
}

PUT/api/trivy/registries/{id}

Update registry credentials or settings.

Auth Required

Parameters

Name	Type	Description
`id`	string	Registry ID

Request Body

JSON

{
  "name": "Production ECR (updated)",
  "credentials": {
    "aws_access_key_id": "AKIANEWKEY...",
    "aws_secret_access_key": "newSecretKey...",
    "aws_region": "us-east-1"
  }
}

DELETE/api/trivy/registries/{id}

Delete registry credentials.

Auth Required

Parameters

Name	Type	Description
`id`	string	Registry ID

POST/api/trivy/registries/{id}/test

Test registry connection with stored credentials.

Auth Required

Parameters

Name	Type	Description
`id`	string	Registry ID

Response

JSON

{
  "success": true,
  "message": "Successfully authenticated to registry",
  "response_time_ms": 245
}

GET/api/trivy/registries/types

Get list of supported registry types with configuration templates.

Auth Required

Response

JSON

{
  "types": [
    {
      "id": "dockerhub",
      "name": "Docker Hub",
      "url_template": "https://index.docker.io/v1/",
      "auth_type": "basic",
      "required_fields": ["username", "password"]
    },
    {
      "id": "ecr",
      "name": "AWS ECR",
      "url_template": "{account_id}.dkr.ecr.{region}.amazonaws.com",
      "auth_type": "ecr",
      "required_fields": ["aws_access_key_id", "aws_secret_access_key", "aws_region"]
    },
    {
      "id": "gcr",
      "name": "Google Artifact Registry",
      "url_template": "{region}-docker.pkg.dev",
      "auth_type": "gcr",
      "required_fields": ["service_account_json"]
    },
    {
      "id": "acr",
      "name": "Azure Container Registry",
      "url_template": "{name}.azurecr.io",
      "auth_type": "acr",
      "required_fields": ["tenant_id", "client_id", "client_secret"]
    }
  ]
}

Admin Endpoints

Organization administration endpoints. Require admin or org_admin role.

Service Tokens

GET/api/admin/service-tokens

List all service tokens for agent authentication.

Auth Required

Response

JSON

{
  "items": [
    {
      "id": "token_123",
      "name": "Production Agents",
      "prefix": "vops_agent_abc",
      "is_active": true,
      "last_used": "2024-01-20T15:30:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST/api/admin/service-tokens

Create a new service token.

Auth Required

Request Body

JSON

{
  "name": "Production Agents",
  "description": "Token for production server agents"
}

Response

JSON

{
  "id": "token_123",
  "name": "Production Agents",
  "token": "vops_agent_abc123def456...",
  "created_at": "2024-01-20T15:30:00Z"
}

PUT/api/admin/service-tokens/{id}/toggle

Enable or disable a service token.

Auth Required

Parameters

Name	Type	Description
`id`	string	Token ID

DELETE/api/admin/service-tokens/{id}

Delete a service token.

Auth Required

Parameters

Name	Type	Description
`id`	string	Token ID

Notification Rules

GET/api/admin/notification-rules

List all notification rules.

Auth Required

Response

JSON

{
  "items": [
    {
      "id": "rule_123",
      "name": "Critical CVE Alert",
      "condition": "cve_severity >= HIGH",
      "channels": ["email", "slack"],
      "is_active": true
    }
  ]
}

POST/api/admin/notification-rules

Create a new notification rule.

Auth Required

Request Body

JSON

{
  "name": "Critical CVE Alert",
  "condition": "cve_severity >= HIGH",
  "channels": ["email", "slack"],
  "recipients": ["[email protected]"]
}

Configuration

GET/api/admin/ldap-config

Get LDAP configuration.

Auth Required

PUT/api/admin/ldap-config

Update LDAP configuration.

Auth Required

Request Body

JSON

{
  "enabled": true,
  "server_url": "ldaps://ldap.example.com:636",
  "bind_dn": "cn=admin,dc=example,dc=com",
  "bind_password": "password",
  "base_dn": "ou=users,dc=example,dc=com"
}

POST/api/admin/ldap-config/test

Test LDAP connection.

Auth Required

GET/api/admin/smtp-config

Get SMTP configuration.

Auth Required

PUT/api/admin/smtp-configcustom_smtp

Update SMTP configuration for email notifications.

Auth Required

Request Body

JSON

{
  "host": "smtp.example.com",
  "port": 587,
  "username": "[email protected]",
  "password": "password",
  "from_address": "[email protected]",
  "use_tls": true
}

CVE Scanning

GET/api/vulnerabilitiescve_scanning

List all detected vulnerabilities.

Auth Required

POST/api/admin/cve/scancve_scanning

Trigger a manual CVE scan.

Auth Required

GET/api/admin/cve/scan-historycve_scanning

Get CVE scan history.

Auth Required

Scheduler

GET/api/admin/scheduler/status

Get scheduler status and running jobs.

Auth Required

GET/api/admin/scheduler-settings

Get scheduler settings.

Auth Required

PUT/api/admin/scheduler-settings

Update scheduler settings.

Auth Required

Request Body

JSON

{
  "cve_scan_interval": 3600,
  "version_check_interval": 86400
}

POST/api/admin/scheduler/restart

Restart the scheduler.

Auth Required

Superadmin Endpoints

Platform administration endpoints. Require is_superadmin: true on user.

Dashboard

GET/api/superadmin/stats

Get platform-wide statistics.

Auth Required

Response

JSON

{
  "total_users": 1250,
  "total_organizations": 85,
  "total_hosts": 3420,
  "active_subscriptions": 72
}

Users

GET/api/superadmin/users

List all users across all organizations.

Auth Required

POST/api/superadmin/users/{id}/toggle

Enable or disable a user account.

Auth Required

Parameters

Name	Type	Description
`id`	string	User ID

DELETE/api/superadmin/users/{id}

Delete a user account.

Auth Required

Parameters

Name	Type	Description
`id`	string	User ID

Organizations

GET/api/superadmin/organizations

List all organizations.

Auth Required

PUT/api/superadmin/organizations/{id}

Update organization settings.

Auth Required

Parameters

Name	Type	Description
`id`	string	Organization ID

DELETE/api/superadmin/organizations/{id}

Delete an organization and all its data.

Auth Required

Parameters

Name	Type	Description
`id`	string	Organization ID

Plans & Features

GET/api/superadmin/plans

List all subscription plans.

Auth Required

PUT/api/superadmin/plans/{id}

Update a subscription plan.

Auth Required

Parameters

Name	Type	Description
`id`	string	Plan ID

GET/api/superadmin/features

List all features.

Auth Required

POST/api/superadmin/features

Create a new feature.

Auth Required

Request Body

JSON

{
  "id": "new_feature",
  "name": "New Feature",
  "description": "Feature description"
}

PUT/api/superadmin/features/{id}

Update a feature.

Auth Required

Parameters

Name	Type	Description
`id`	string	Feature ID

DELETE/api/superadmin/features/{id}

Delete a feature.

Auth Required

Parameters

Name	Type	Description
`id`	string	Feature ID

Templates

GET/api/superadmin/templates

List application configuration templates.

Auth Required

Parameters

Name	Type	Description
`status`	string	Filter by status (draft, published, archived)
`category`	string	Filter by category

POST/api/superadmin/templates

Create a new template (draft).

Auth Required

POST/api/superadmin/templates/{id}/publish

Publish a draft template.

Auth Required

Parameters

Name	Type	Description
`id`	string	Template ID

POST/api/superadmin/templates/{id}/archive

Archive a published template.

Auth Required

Parameters

Name	Type	Description
`id`	string	Template ID

Agent Endpoints

Endpoints for host agents using service tokens. Authenticate with Authorization: Bearer vops_agent_...

POST/api/agents/register

Auth Required

Request Body

JSON

{
  "hostname": "server-01",
  "ip_address": "192.168.1.10",
  "os": "Ubuntu 22.04",
  "agent_version": "1.0.0"
}

Response

JSON

{
  "host_id": "host_123",
  "hostname": "server-01",
  "status": "registered"
}

POST/api/hosts/{host_id}/collect

Submit collected application data from host.

Auth Required

Parameters

Name	Type	Description
`host_id`	string	Host ID returned from registration

Request Body

JSON

{
  "applications": [
    {"name": "nginx", "version": "1.24.0"},
    {"name": "postgresql", "version": "15.2"},
    {"name": "redis", "version": "7.2.3"}
  ]
}

Response

JSON

{
  "status": "success",
  "applications_updated": 3,
  "timestamp": "2024-01-20T15:30:00Z"
}

Error Handling

All errors follow a consistent format with appropriate HTTP status codes.

Error Response Format

JSON

{
  "detail": "Error message describing what went wrong"
}

Status Code	Meaning	Description
`400`	Bad Request	Invalid input or missing required fields
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	Insufficient permissions for this action
`404`	Not Found	Requested resource does not exist
`422`	Validation Error	Request body validation failed
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal server error

Rate Limiting

API requests are rate limited to ensure fair usage:

Default: 100 requests/minute per IP
Auth endpoints: 10 requests/minute
Agent endpoints: 1000 requests/minute

When rate limited, you will receive a 429 response. The Retry-After header indicates when you can retry.

Pagination

All list endpoints support pagination with consistent parameters and response format.

Request Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`limit`	integer	20	Items per page (max: 100). Some endpoints use `per_page`.

Response Format

Response keys vary by resource type:

JSON

// Projects endpoint
{
  "projects": [...],
  "total": 150,
  "page": 1
}

// Dependencies endpoint
{
  "dependencies": [...],
  "total": 50,
  "page": 1
}

// Other endpoints (hosts, applications, etc.)
{
  "items": [...],
  "total": 150,
  "page": 1
}

Example: Fetching Page 2 with 50 items

HTTP

GET /api/projects?page=2&limit=50

Ready to Integrate?

Create your account and get your API token to start building.

Get Started Free