{ "openapi": "3.0.3", "info": { "title": "Virtum tenant API", "version": "1.1.0", "description": "Published read contracts. Internal and agent APIs are not implicitly public." }, "servers": [ { "url": "/" } ], "tags": [ { "name": "Deploy" }, { "name": "Platform" }, { "name": "Operations" }, { "name": "Security" }, { "name": "Models" } ], "paths": { "/api/v1/fleet/assets": { "get": { "operationId": "listFleetAssets", "summary": "List fleet assets", "description": "Non-decommissioned inventory in the credential\u2019s tenant, ordered by hostname then id (assets without a hostname first).", "tags": [ "Deploy" ], "parameters": [ { "name": "limit", "in": "query", "description": "Rows per page (out-of-range values are clamped to 1\u2013200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "meta.next_cursor from the previous page, passed back unchanged. Omit for the first page.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "One page of the tenant-scoped collection", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FleetAsset" } }, "meta": { "$ref": "#/components/schemas/PageMetadata" } } }, "example": { "data": [ { "id": "example-asset", "asset_key": "example-server", "hostname": "server.example.invalid", "type": "server", "platform": "linux", "os": "Ubuntu 24.04", "health": "healthy", "claim_status": null, "exposure": null, "last_seen_at": null } ], "meta": { "count": 1, "limit": 50, "truncated": false, "next_cursor": null } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } } }, "401": { "description": "Invalid, expired, revoked or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "unauthorized" } } } }, "403": { "description": "The credential lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "scope_required", "scope": "fleet.read", "granted": [ "events.read" ] } } } }, "422": { "description": "Invalid query parameter or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "cursor": [ "The cursor is not one this endpoint issued. Pass meta.next_cursor back unchanged." ] } } } } }, "429": { "description": "Tenant rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "rate_limited", "message": "This workspace has used its 120 requests for this minute.", "retry_after_seconds": 42 } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry." } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "fleet.read" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/deploy" } }, "/api/v1/events": { "get": { "operationId": "listEvents", "summary": "List platform events", "description": "Tenant-attributed events, newest ingestion first. Platform-wide events with no tenant are excluded.", "tags": [ "Platform" ], "parameters": [ { "name": "limit", "in": "query", "description": "Rows per page (out-of-range values are clamped to 1\u2013200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "meta.next_cursor from the previous page, passed back unchanged. Omit for the first page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "type", "in": "query", "description": "Exact event type, for example monitoring.alert.opened.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "since", "in": "query", "description": "Exclusive ingestion-time lower bound (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "One page of the tenant-scoped collection", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignalEvent" } }, "meta": { "$ref": "#/components/schemas/PageMetadata" } } }, "example": { "data": [ { "id": "example-event", "type": "monitoring.alert.opened", "class": "health", "severity": "warning", "outcome": null, "service": "monitoring", "summary": "Example alert opened", "entity": { "type": "monitor_alert", "id": "example-alert" }, "occurred_at": "2026-10-03T12:00:00+00:00", "ingested_at": "2026-10-03T12:00:01+00:00" } ], "meta": { "count": 1, "limit": 50, "truncated": false, "next_cursor": null } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } } }, "401": { "description": "Invalid, expired, revoked or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "unauthorized" } } } }, "403": { "description": "The credential lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "scope_required", "scope": "events.read", "granted": [ "events.read" ] } } } }, "422": { "description": "Invalid query parameter or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "cursor": [ "The cursor is not one this endpoint issued. Pass meta.next_cursor back unchanged." ] } } } } }, "429": { "description": "Tenant rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "rate_limited", "message": "This workspace has used its 120 requests for this minute.", "retry_after_seconds": 42 } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry." } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "events.read" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/events" } }, "/api/v1/incidents": { "get": { "operationId": "listIncidents", "summary": "List incidents", "description": "Incidents in the credential\u2019s tenant, newest first. Signals, impact and runbook metadata are not part of the projection.", "tags": [ "Operations" ], "parameters": [ { "name": "limit", "in": "query", "description": "Rows per page (out-of-range values are clamped to 1\u2013200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "meta.next_cursor from the previous page, passed back unchanged. Omit for the first page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "status", "in": "query", "description": "Exact status, for example open, mitigating or resolved.", "schema": { "type": "string", "maxLength": 40 } }, { "name": "severity", "in": "query", "description": "Exact severity, for example sev1, sev2 or sev3.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "One page of the tenant-scoped collection", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "meta": { "$ref": "#/components/schemas/PageMetadata" } } }, "example": { "data": [ { "id": "01JEXAMPLEINCIDENT00000000", "title": "API latency above target", "summary": "p95 latency over 2s on the public API.", "severity": "sev2", "status": "mitigating", "affected_service": "api", "project_id": null, "detected_at": "2026-10-03T12:00:00+00:00", "resolved_at": null, "created_at": "2026-10-03T12:00:05+00:00", "updated_at": "2026-10-03T12:20:00+00:00" } ], "meta": { "count": 1, "limit": 50, "truncated": false, "next_cursor": null } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } } }, "401": { "description": "Invalid, expired, revoked or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "unauthorized" } } } }, "403": { "description": "The credential lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "scope_required", "scope": "incidents.read", "granted": [ "events.read" ] } } } }, "422": { "description": "Invalid query parameter or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "cursor": [ "The cursor is not one this endpoint issued. Pass meta.next_cursor back unchanged." ] } } } } }, "429": { "description": "Tenant rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "rate_limited", "message": "This workspace has used its 120 requests for this minute.", "retry_after_seconds": 42 } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry." } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "incidents.read" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/operations" } }, "/api/v1/security/findings": { "get": { "operationId": "listSecurityFindings", "summary": "List security findings", "description": "Security findings in the credential\u2019s tenant, newest first. Scanner detail and analyst notes are excluded.", "tags": [ "Security" ], "parameters": [ { "name": "limit", "in": "query", "description": "Rows per page (out-of-range values are clamped to 1\u2013200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "meta.next_cursor from the previous page, passed back unchanged. Omit for the first page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "status", "in": "query", "description": "Exact status, for example open, resolved or remediated.", "schema": { "type": "string", "maxLength": 40 } }, { "name": "severity", "in": "query", "description": "Exact severity: low, medium, high or critical.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "One page of the tenant-scoped collection", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityFinding" } }, "meta": { "$ref": "#/components/schemas/PageMetadata" } } }, "example": { "data": [ { "id": "01JEXAMPLEFINDING000000000", "type": "vulnerability", "severity": "high", "status": "open", "title": "Outdated OpenSSL on web-01", "summary": null, "source": "scanner", "project_id": null, "environment_id": null, "target_id": null, "detected_at": "2026-10-03T12:00:00+00:00", "resolved_at": null, "created_at": "2026-10-03T12:00:00+00:00", "updated_at": "2026-10-03T12:00:00+00:00" } ], "meta": { "count": 1, "limit": 50, "truncated": false, "next_cursor": null } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } } }, "401": { "description": "Invalid, expired, revoked or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "unauthorized" } } } }, "403": { "description": "The credential lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "scope_required", "scope": "findings.read", "granted": [ "events.read" ] } } } }, "422": { "description": "Invalid query parameter or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "cursor": [ "The cursor is not one this endpoint issued. Pass meta.next_cursor back unchanged." ] } } } } }, "429": { "description": "Tenant rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "rate_limited", "message": "This workspace has used its 120 requests for this minute.", "retry_after_seconds": 42 } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry." } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "findings.read" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/security" } }, "/api/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "description": "The workspaces (dev, prod, a client\u2026) inside the credential\u2019s tenant, by name.", "tags": [ "Platform" ], "parameters": [ { "name": "limit", "in": "query", "description": "Rows per page (out-of-range values are clamped to 1\u2013200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "meta.next_cursor from the previous page, passed back unchanged. Omit for the first page.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "One page of the tenant-scoped collection", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "meta": { "$ref": "#/components/schemas/PageMetadata" } } }, "example": { "data": [ { "id": "01JEXAMPLEWORKSPACE0000000", "name": "Production", "description": null, "status": "active", "created_at": "2026-09-24T19:00:00+00:00", "updated_at": "2026-09-24T19:00:00+00:00" } ], "meta": { "count": 1, "limit": 50, "truncated": false, "next_cursor": null } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } } }, "401": { "description": "Invalid, expired, revoked or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "unauthorized" } } } }, "403": { "description": "The credential lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "scope_required", "scope": "workspaces.read", "granted": [ "events.read" ] } } } }, "422": { "description": "Invalid query parameter or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "cursor": [ "The cursor is not one this endpoint issued. Pass meta.next_cursor back unchanged." ] } } } } }, "429": { "description": "Tenant rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "rate_limited", "message": "This workspace has used its 120 requests for this minute.", "retry_after_seconds": 42 } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry." } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "workspaces.read" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/tenancy" } }, "/api/v1/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "description": "Projects in the credential\u2019s tenant, by name. Filter by workspace_id to list one workspace.", "tags": [ "Platform" ], "parameters": [ { "name": "limit", "in": "query", "description": "Rows per page (out-of-range values are clamped to 1\u2013200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "meta.next_cursor from the previous page, passed back unchanged. Omit for the first page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "workspace_id", "in": "query", "description": "Only projects in this workspace (an id from List workspaces).", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "One page of the tenant-scoped collection", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "$ref": "#/components/schemas/PageMetadata" } } }, "example": { "data": [ { "id": "01JEXAMPLEPROJECT000000000", "name": "Customer portal", "slug": "customer-portal", "kind": "app", "status": "active", "description": null, "workspace_id": "01JEXAMPLEWORKSPACE0000000", "primary_language": "php", "primary_framework": "laravel", "created_at": "2026-09-24T19:00:00+00:00", "updated_at": "2026-10-01T09:30:00+00:00" } ], "meta": { "count": 1, "limit": 50, "truncated": false, "next_cursor": null } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } } }, "401": { "description": "Invalid, expired, revoked or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "unauthorized" } } } }, "403": { "description": "The credential lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "scope_required", "scope": "projects.read", "granted": [ "events.read" ] } } } }, "422": { "description": "Invalid query parameter or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The given data was invalid.", "errors": { "cursor": [ "The cursor is not one this endpoint issued. Pass meta.next_cursor back unchanged." ] } } } } }, "429": { "description": "Tenant rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "rate_limited", "message": "This workspace has used its 120 requests for this minute.", "retry_after_seconds": 42 } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry." } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "projects.read" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/tenancy" } }, "/api/v1/approvals/summary": { "get": { "operationId": "getApprovalSummary", "summary": "Get the approvals summary", "description": "How many decisions are waiting in the tenant\u2019s approvals inbox, per service. Counts only: the items themselves, and deciding them, stay in Virtum.", "tags": [ "Platform" ], "parameters": [], "responses": { "200": { "description": "The tenant-scoped object", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalSummary" } } }, "example": { "data": { "pending": 3, "by_service": { "deploy": 1, "security": 2, "autonomy": 0, "ai_runs": 0, "access": 0, "platform": 0, "operations": 0, "docs": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } } }, "401": { "description": "Invalid, expired, revoked or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "unauthorized" } } } }, "403": { "description": "The credential lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "scope_required", "scope": "approvals.read", "granted": [ "events.read" ] } } } }, "429": { "description": "Tenant rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "rate_limited", "message": "This workspace has used its 120 requests for this minute.", "retry_after_seconds": 42 } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry." } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "approvals.read" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/sandbox" } }, "/api/v1/models": { "get": { "x-virtum-limits": [ "Workspace fair-use limit with X-RateLimit-* headers." ], "operationId": "listModels", "summary": "List models", "description": "The Virtum models this key may call, with capabilities and published per-token prices. Only models live for your workspace and allowed for this key appear.", "tags": [ "Models" ], "parameters": [], "responses": { "200": { "description": "List models", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "example": { "object": "list", "data": [ { "id": "virtum/example-model", "object": "model", "created": 1760054400, "owned_by": "virtum", "name": "Example model", "context_length": 131072, "max_output_tokens": 8192, "features": [ "streaming", "tools" ], "route_policy": "named_model", "privacy_profile": "shared_api", "regions": [], "pricing": { "currency": "GBP", "unit": "per 1,000,000 tokens", "rate_card_version": 1, "rates": { "input_tokens": "0.50", "output_tokens": "1.50" } } } ] } } } }, "404": { "description": "model_api_disabled: The model API is not enabled on this platform.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "403": { "description": "key_not_enabled_for_models: The credential has the models.invoke scope but no model-access policy; create keys on the Model access page. key_owner_not_permitted: The person who owns this key is no longer allowed to use paid models in the workspace. consumption_not_allowed: Workspace policy does not let this key's owner consume paid models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "401": { "description": "Invalid or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "models.invoke" ], "x-virtum-safety": "read", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/models" } }, "/api/v1/chat/completions": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "example": { "model": "virtum/example-model", "messages": [ { "role": "user", "content": "Hello" } ], "max_tokens": 256, "stream": false } } } }, "x-virtum-limits": [ "Text chat only: message content is a string or a list of {type: text} parts. Images, audio and files are refused (unsupported_content).", "tools / tool_choice and response_format only on models whose features list them; otherwise feature_not_supported.", "Refused by name (unsupported_parameter): n, logprobs, top_logprobs, logit_bias, audio, modalities, prediction, web_search_options, functions, function_call, service_tier, store, metadata, parallel_tool_calls, reasoning_effort.", "max_tokens (or max_completion_tokens) is capped at the model's max_output_tokens; when omitted, 4096 (or the model limit if lower).", "Body at most 1,000,000 bytes and 500 messages.", "Per-key requests per minute and requests in flight are set on the key; the workspace also has a fair-use limit with X-RateLimit-* headers.", "Idempotency-Key header (optional, up to 191 characters): the same key with the same body replays the saved non-streamed result; a different body is 409 idempotency_key_reused; streamed requests are never replayed.", "Streams end with data: [DONE]; an error mid-stream is sent as a final error event and the stream is not resumed or replayed." ], "x-virtum-billing": [ "Each request first holds its worst case (every input byte as a token plus max_tokens) at the published rate card; the hold is released down to the real charge.", "You are charged from the model's own reported usage: input, cached input and output tokens at the rates in /v1/models. Reasoning tokens are part of output tokens and are not charged twice.", "When the model reports no usage (for example a dropped stream), the charge is pending until reconciled from the model operator's records. You are never charged the held maximum.", "A call that produced no output (refused or failed before the model ran) is not charged. Retries happen only within the same model and only before any output reached you.", "X-Virtum-Request-Id identifies the request; X-Virtum-Billing is settled or pending_reconciliation; X-Virtum-Charge carries the settled amount." ], "operationId": "createChatCompletion", "summary": "Create a chat completion", "description": "OpenAI-compatible chat completions, streamed or not, within the protocol limits below. Billed per token from prepaid model credit.", "tags": [ "Models" ], "parameters": [], "responses": { "200": { "description": "Create a chat completion", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Per-tenant rate limit metadata; Reset is Unix time." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" }, "example": { "id": "chatcmpl-01J0EXAMPLE", "object": "chat.completion", "created": 1760054400, "model": "virtum/example-model", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 7, "total_tokens": 16, "prompt_tokens_details": { "cached_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0 } } } } } }, "404": { "description": "model_api_disabled: The model API is not enabled on this platform. model_not_found: No model with that id is available to this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "403": { "description": "key_not_enabled_for_models: The credential has the models.invoke scope but no model-access policy; create keys on the Model access page. key_owner_not_permitted: The person who owns this key is no longer allowed to use paid models in the workspace. consumption_not_allowed: Workspace policy does not let this key's owner consume paid models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "402": { "description": "payer_unavailable: The workspace has no active billing account for model usage. insufficient_balance: The prepaid balance cannot cover this request's worst case. monthly_limit_reached: The workspace's monthly spend limit would be passed. key_budget_exhausted: This key's monthly budget would be passed. allowance_exhausted: The key owner's monthly member allowance would be passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "400": { "description": "invalid_request: The body is not a valid chat completion request. unsupported_parameter: A parameter this API deliberately does not support (it would change billed output in a way that is not metered). unknown_parameter: A parameter this API does not recognise. feature_not_supported: The model does not declare the feature this parameter needs (tools, structured output). unsupported_content: Only text message content is supported. max_tokens_too_large: max_tokens exceeds the model's output limit. upstream_rejected_request: The model rejected the request as invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "413": { "description": "request_too_large: The request body is larger than the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "409": { "description": "idempotency_key_reused: The Idempotency-Key was already used with a different request body. request_in_progress: A request with this Idempotency-Key is still running. stream_not_replayable: A streamed request is never replayed; use a new Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "429": { "description": "key_rate_limited: This key passed its requests-per-minute limit. concurrency_limit: This key has its maximum number of requests in flight.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "503": { "description": "dispatch_paused: Model dispatch is paused by an operator. no_eligible_supply: No eligible capacity can serve this model right now. supply_budget_exhausted: Capacity budget for this model is exhausted right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "502": { "description": "upstream_error: The model failed to answer. You are not charged for a call that produced nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "504": { "description": "upstream_timeout: The model did not answer in time. Any charge is settled from authoritative usage, never guessed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelApiError" } } } }, "401": { "description": "Invalid or missing credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "tenantCredential": [] } ], "x-virtum-scopes": [ "models.invoke" ], "x-virtum-safety": "billable", "deprecated": false, "x-virtum-replacement": null, "x-virtum-sunset": null, "x-virtum-guide": "/developers/docs/models" } } }, "components": { "schemas": { "FleetAsset": { "type": "object", "additionalProperties": false, "required": [ "id", "asset_key", "hostname", "type", "platform", "os", "health", "claim_status", "exposure", "last_seen_at" ], "properties": { "id": { "type": "string", "nullable": false }, "asset_key": { "type": "string", "nullable": false }, "hostname": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "os": { "type": "string", "nullable": true }, "health": { "type": "string", "nullable": true }, "claim_status": { "type": "string", "nullable": true }, "exposure": { "type": "string", "nullable": true }, "last_seen_at": { "type": "string", "nullable": true, "format": "date-time" } }, "description": "Public fleet projection. Internal identifiers, agent secrets and connector configuration are excluded.", "example": { "id": "example-asset", "asset_key": "example-server", "hostname": "server.example.invalid", "type": "server", "platform": "linux", "os": "Ubuntu 24.04", "health": "healthy", "claim_status": null, "exposure": null, "last_seen_at": null } }, "SignalEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "class", "severity", "outcome", "service", "summary", "entity", "occurred_at", "ingested_at" ], "properties": { "id": { "type": "string", "nullable": false }, "type": { "type": "string", "nullable": false }, "class": { "type": "string", "nullable": false }, "severity": { "type": "string", "nullable": false }, "outcome": { "type": "string", "nullable": true }, "service": { "type": "string", "nullable": false }, "summary": { "type": "string", "nullable": true }, "entity": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true } } }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" }, "ingested_at": { "type": "string", "nullable": true, "format": "date-time" } }, "description": "Tenant event read projection. Payload attributes are deliberately excluded.", "example": { "id": "example-event", "type": "monitoring.alert.opened", "class": "health", "severity": "warning", "outcome": null, "service": "monitoring", "summary": "Example alert opened", "entity": { "type": "monitor_alert", "id": "example-alert" }, "occurred_at": "2026-10-03T12:00:00+00:00", "ingested_at": "2026-10-03T12:00:01+00:00" } }, "Incident": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "summary", "severity", "status", "affected_service", "project_id", "detected_at", "resolved_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "nullable": false }, "title": { "type": "string", "nullable": false }, "summary": { "type": "string", "nullable": true }, "severity": { "type": "string", "nullable": false }, "status": { "type": "string", "nullable": false }, "affected_service": { "type": "string", "nullable": true }, "project_id": { "type": "string", "nullable": true }, "detected_at": { "type": "string", "nullable": true, "format": "date-time" }, "resolved_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time" } }, "description": "Public incident projection. Signals, impact, scope and runbook metadata are excluded.", "example": { "id": "01JEXAMPLEINCIDENT00000000", "title": "API latency above target", "summary": "p95 latency over 2s on the public API.", "severity": "sev2", "status": "mitigating", "affected_service": "api", "project_id": null, "detected_at": "2026-10-03T12:00:00+00:00", "resolved_at": null, "created_at": "2026-10-03T12:00:05+00:00", "updated_at": "2026-10-03T12:20:00+00:00" } }, "SecurityFinding": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "severity", "status", "title", "summary", "source", "project_id", "environment_id", "target_id", "detected_at", "resolved_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "nullable": false }, "type": { "type": "string", "nullable": false }, "severity": { "type": "string", "nullable": false }, "status": { "type": "string", "nullable": false }, "title": { "type": "string", "nullable": false }, "summary": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": false }, "project_id": { "type": "string", "nullable": true }, "environment_id": { "type": "string", "nullable": true }, "target_id": { "type": "string", "nullable": true }, "detected_at": { "type": "string", "nullable": true, "format": "date-time" }, "resolved_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time" } }, "description": "Public finding projection. Scanner detail (details_json) and analyst notes are excluded.", "example": { "id": "01JEXAMPLEFINDING000000000", "type": "vulnerability", "severity": "high", "status": "open", "title": "Outdated OpenSSL on web-01", "summary": null, "source": "scanner", "project_id": null, "environment_id": null, "target_id": null, "detected_at": "2026-10-03T12:00:00+00:00", "resolved_at": null, "created_at": "2026-10-03T12:00:00+00:00", "updated_at": "2026-10-03T12:00:00+00:00" } }, "Workspace": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "nullable": false }, "name": { "type": "string", "nullable": false }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": false }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time" } }, "description": "A workspace inside the tenant (dev, prod, a client\u2026). Members and items are not part of this projection.", "example": { "id": "01JEXAMPLEWORKSPACE0000000", "name": "Production", "description": null, "status": "active", "created_at": "2026-09-24T19:00:00+00:00", "updated_at": "2026-09-24T19:00:00+00:00" } }, "Project": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "kind", "status", "description", "workspace_id", "primary_language", "primary_framework", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "nullable": false }, "name": { "type": "string", "nullable": false }, "slug": { "type": "string", "nullable": false }, "kind": { "type": "string", "nullable": false }, "status": { "type": "string", "nullable": false }, "description": { "type": "string", "nullable": true }, "workspace_id": { "type": "string", "nullable": true }, "primary_language": { "type": "string", "nullable": true }, "primary_framework": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time" } }, "description": "A project in the tenant. Storage metadata, lineage and the creator are excluded.", "example": { "id": "01JEXAMPLEPROJECT000000000", "name": "Customer portal", "slug": "customer-portal", "kind": "app", "status": "active", "description": null, "workspace_id": "01JEXAMPLEWORKSPACE0000000", "primary_language": "php", "primary_framework": "laravel", "created_at": "2026-09-24T19:00:00+00:00", "updated_at": "2026-10-01T09:30:00+00:00" } }, "ApprovalSummary": { "type": "object", "additionalProperties": false, "required": [ "pending", "by_service" ], "description": "Counts of decisions waiting in the approvals inbox. The items, and deciding them, stay in Virtum.", "properties": { "pending": { "type": "integer" }, "by_service": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Pending count per service, for example deploy, security, operations." } }, "example": { "pending": 3, "by_service": { "deploy": 1, "security": 2, "autonomy": 0, "ai_runs": 0, "access": 0, "platform": 0, "operations": 0, "docs": 0 } } }, "PageMetadata": { "type": "object", "required": [ "count", "limit", "truncated", "next_cursor" ], "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "truncated": { "type": "boolean", "description": "True when another page exists." }, "next_cursor": { "type": "string", "nullable": true, "description": "Pass as ?cursor= for the next page; null on the last page." } }, "description": "Keyset page metadata. Walk the list by passing next_cursor back until it is null." }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "scope": { "type": "string" }, "granted": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "retry_after_seconds": { "type": "integer" } }, "description": "Existing credential/scope/rate-limit failures. Validation failures use ValidationError." }, "ValidationError": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Model": { "type": "object", "required": [ "id", "object", "owned_by", "pricing" ], "description": "A Virtum model product. Customer-facing fields only: who operates the underlying capacity and its wholesale price are never part of this object.", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created": { "type": "integer" }, "owned_by": { "type": "string" }, "name": { "type": "string" }, "context_length": { "type": "integer", "nullable": true }, "max_output_tokens": { "type": "integer", "nullable": true }, "features": { "type": "array", "items": { "type": "string" } }, "route_policy": { "type": "string" }, "privacy_profile": { "type": "string" }, "regions": { "type": "array", "items": { "type": "string" } }, "pricing": { "type": "object", "properties": { "currency": { "type": "string" }, "unit": { "type": "string" }, "rate_card_version": { "type": "integer" }, "rates": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "example": { "id": "virtum/example-model", "object": "model", "created": 1760054400, "owned_by": "virtum", "name": "Example model", "context_length": 131072, "max_output_tokens": 8192, "features": [ "streaming", "tools" ], "route_policy": "named_model", "privacy_profile": "shared_api", "regions": [], "pricing": { "currency": "GBP", "unit": "per 1,000,000 tokens", "rate_card_version": 1, "rates": { "input_tokens": "0.50", "output_tokens": "1.50" } } } }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "description": "The accepted subset of the OpenAI chat completion request. Unknown and unsupported parameters are refused, never ignored.", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object" } }, "max_tokens": { "type": "integer" }, "max_completion_tokens": { "type": "integer" }, "stream": { "type": "boolean" }, "stream_options": { "type": "object" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "stop": { "type": "array", "items": { "type": "string" } }, "presence_penalty": { "type": "number" }, "frequency_penalty": { "type": "number" }, "seed": { "type": "integer" }, "user": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object" } }, "tool_choice": { "type": "string" }, "response_format": { "type": "object" } } }, "ChatCompletion": { "type": "object", "required": [ "id", "object", "model", "choices" ], "description": "A completion. Streamed responses are chat.completion.chunk events of the same shape with delta in place of message.", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object" } }, "usage": { "type": "object" } } }, "ModelApiError": { "type": "object", "required": [ "error" ], "description": "OpenAI-shaped error; error.code is the stable value to switch on.", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string" }, "param": { "type": "string", "nullable": true } } } } } }, "securitySchemes": { "tenantCredential": { "type": "http", "scheme": "bearer", "description": "Tenant-bound vk credential. Required scope is declared by x-virtum-scopes." } } } }