VB-OS Python SDK Complete Reference

Client classes

Class	Description
`VBOSClient`	Synchronous client
`AsyncVBOSClient`	Asynchronous client (identical interface, all methods are `async`)

Both accept the same constructor parameters:

VBOSClient(
    api_key: str,
    base_url: str = "https://api.vb-os.org",
    max_retries: int = 3,
    timeout: float = 30.0,
)

Top-level methods

Method	Signature	Returns	Description
`verify`	`(workload, project=None, boundary_ref=None, metadata=None)`	`EvaluationResult`	Submit workload for evaluation
`verify_batch`	`(workloads, project=None, boundary_ref=None)`	`dict`	Submit multiple workloads
`validate`	`(workload, project=None, boundary_ref=None)`	`dict`	Validate without recording
`certify`	`(project_id, **kwargs)`	`dict`	Initiate certification run
`replay`	`(project_id, evaluation_id)`	`ReplayResult`	Replay evaluation (deprecated)
`close`	`()`	`None`	Close HTTP client

Resource namespaces

All namespaces are properties on the client. Each has sync and async variants. All list methods accept limit: int = 20 and cursor: str | None = None for pagination.

client.account

Method	Signature	Description
`delete`	`()`	Request account deletion
`cancel_delete`	`()`	Cancel pending deletion
`deletion_status`	`()`	Check deletion status
`export`	`()`	Request data export
`export_latest`	`()`	Get latest export
`export_status`	`(export_id)`	Check export status
`export_download`	`(export_id)`	Download export

client.alert_rules

Method	Signature	Description
`create`	`(project_id, **kwargs)`	Create an alert rule
`list`	`(project_id, *, limit=20, cursor=None)`	List alert rules
`get`	`(project_id, rule_id)`	Get an alert rule
`update`	`(project_id, rule_id, **kwargs)`	Update an alert rule
`delete`	`(project_id, rule_id)`	Delete an alert rule

client.analytics

Method	Signature	Description
`assertion_rate`	`(project_id, **kwargs)`	Assertion rate over time
`deferral_rate`	`(project_id, **kwargs)`	Deferral rate over time
`evaluations`	`(project_id, **kwargs)`	Evaluation volume summary
`failure_reasons`	`(project_id, **kwargs)`	Failure reason breakdown
`latency`	`(project_id, **kwargs)`	Evaluation latency stats

client.audit_log

Method	Signature	Description
`list`	`(, limit=20, cursor=None, *kwargs)`	List audit log entries
`export`	`(**kwargs)`	Request audit log export
`export_status`	`(export_id)`	Check export status

client.billing

Method	Signature	Description
`usage`	`(**kwargs)`	Get usage summary
`subscription`	`()`	Get subscription details
`invoices`	`(**kwargs)`	List invoices

client.boundaries

Method	Signature	Description
`list`	`(project_id, *, limit=20, cursor=None)`	List boundaries
`create`	`(project_id, **kwargs)`	Create a boundary
`get`	`(project_id, boundary_ref)`	Get a boundary
`update_draft`	`(project_id, boundary_ref, **kwargs)`	Update draft version
`submit`	`(project_id, boundary_ref)`	Submit for review
`versions`	`(project_id, boundary_ref, *, limit=20, cursor=None)`	List versions
`get_version`	`(project_id, boundary_ref, version_id)`	Get a version
`approve`	`(project_id, boundary_ref, version_id)`	Approve a version
`reject`	`(project_id, boundary_ref, version_id)`	Reject a version
`diff`	`(project_id, boundary_ref, **kwargs)`	Diff two versions

client.certification_models

Method	Signature	Description
`list`	`(project_id, *, limit=20, cursor=None)`	List certification models
`create`	`(project_id, **kwargs)`	Create a certification model
`create_version`	`(project_id, model_id, **kwargs)`	Create a model version

client.certifications

Method	Signature	Description
`list`	`(project_id, *, limit=20, cursor=None)`	List certification runs
`get`	`(project_id, run_id)`	Get a certification run
`get_report`	`(project_id, run_id)`	Get the certification report
`wait`	`(project_id, run_id, *, poll_interval_seconds=2.0, max_attempts=150)`	Poll until run completes

client.connector_providers

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List available providers
`schema`	`(provider_id)`	Get provider config schema

client.connectors

Method	Signature	Description
`create`	`(project_id, **kwargs)`	Create a connector
`list`	`(project_id, *, limit=20, cursor=None)`	List connectors
`get`	`(project_id, connector_id)`	Get a connector
`update`	`(project_id, connector_id, **kwargs)`	Update a connector
`delete`	`(project_id, connector_id)`	Delete a connector
`test`	`(project_id, connector_id)`	Test connection
`gather`	`(project_id, connector_id, **kwargs)`	Trigger evidence gathering
`analytics`	`(project_id, **kwargs)`	Connector analytics
`resources`	`(project_id, connector_id, *, limit=20, cursor=None)`	List discovered resources
`schema`	`(project_id, connector_id)`	Get connector schema
`get_schedule`	`(project_id, connector_id)`	Get gather schedule
`set_schedule`	`(project_id, connector_id, **kwargs)`	Set gather schedule
`list_gathers`	`(project_id, connector_id, *, limit=20, cursor=None)`	List gather runs
`authorize`	`(project_id, connector_id, *, mode="REMOTE")`	Start OAuth authorization
`disconnect`	`(project_id, connector_id)`	Disconnect OAuth
`reconnect`	`(project_id, connector_id, *, mode="REMOTE")`	Reconnect OAuth
`oauth_status`	`(project_id, connector_id)`	Check OAuth status
`wait_for_authorization`	`(authorization_id, *, timeout=600, poll_interval=3)`	Poll until OAuth completes

client.deployments

Method	Signature	Description
`list`	`(project_id, environment_id, *, limit=20, cursor=None)`	List deployments
`create`	`(project_id, environment_id, **kwargs)`	Create a deployment
`active`	`(project_id, environment_id)`	Get active deployment
`approve`	`(project_id, environment_id, deployment_id)`	Approve a deployment
`reject`	`(project_id, environment_id, deployment_id)`	Reject a deployment
`promote`	`(project_id, environment_id, , source_environment, boundary_version_id, *kwargs)`	Promote from another environment
`rollback`	`(project_id, environment_id, **kwargs)`	Rollback to a prior deployment

client.environments

Method	Signature	Description
`list`	`(project_id, *, limit=20, cursor=None)`	List environments
`create`	`(project_id, **kwargs)`	Create an environment
`get`	`(project_id, environment_id)`	Get an environment
`update`	`(project_id, environment_id, **kwargs)`	Update an environment
`deactivate`	`(project_id, environment_id)`	Deactivate an environment
`reactivate`	`(project_id, environment_id)`	Reactivate an environment

client.evaluations

Method	Signature	Description
`list`	`(project_id, *, limit=20, cursor=None)`	List evaluations
`get`	`(project_id, evaluation_id)`	Get evaluation detail
`replay`	`(project_id, evaluation_id)`	Replay an evaluation
`export`	`(project_id, **kwargs)`	Request evaluation export
`share`	`(project_id, evaluation_id)`	Create a share link
`get_shared`	`(token)`	Retrieve a shared evaluation

client.flow_templates

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List flow templates
`get`	`(slug)`	Get a flow template

client.flows

Method	Signature	Description
`create`	`(project_id, **kwargs)`	Create a flow
`list`	`(project_id, *, limit=20, cursor=None)`	List flows
`get`	`(project_id, flow_id)`	Get a flow
`update`	`(project_id, flow_id, **kwargs)`	Update a flow
`delete`	`(project_id, flow_id)`	Delete a flow
`export`	`(project_id, flow_id)`	Export flow definition
`import_flow`	`(project_id, **kwargs)`	Import a flow
`from_template`	`(project_id, **kwargs)`	Create from template
`create_version`	`(project_id, flow_id, **kwargs)`	Create a flow version
`list_versions`	`(project_id, flow_id, *, limit=20, cursor=None)`	List flow versions
`get_version`	`(project_id, flow_id, version_id)`	Get a flow version
`update_version`	`(project_id, flow_id, version_id, **kwargs)`	Update a flow version
`delete_version`	`(project_id, flow_id, version_id)`	Delete a flow version
`approve_version`	`(project_id, flow_id, version_id)`	Approve a flow version
`deploy`	`(project_id, flow_id, version_id, **kwargs)`	Deploy a flow version
`suspend`	`(project_id, flow_id, deployment_id)`	Suspend a deployment
`dry_run`	`(project_id, flow_id, version_id, **kwargs)`	Execute a dry run
`list_executions`	`(project_id, flow_id, *, limit=20, cursor=None)`	List executions
`reconstruct_execution`	`(project_id, flow_id, execution_id)`	Reconstruct an execution

client.governed_workspaces

Method	Signature	Description
`create`	`(project_id, **kwargs)`	Create a governed workspace
`list`	`(project_id, *, limit=20, cursor=None)`	List governed workspaces
`get`	`(project_id, workspace_id)`	Get a governed workspace
`create_version`	`(project_id, workspace_id, **kwargs)`	Create a version
`get_version`	`(project_id, workspace_id, version_id)`	Get a version
`submit`	`(project_id, workspace_id, version_id)`	Submit for review
`approve`	`(project_id, workspace_id, version_id)`	Approve a version
`deploy`	`(project_id, workspace_id, version_id)`	Deploy a version
`archive`	`(project_id, workspace_id, version_id)`	Archive a version
`create_instance`	`(project_id, workspace_id, **kwargs)`	Create an instance
`submit_instance`	`(project_id, workspace_id, instance_id)`	Submit an instance
`get_instance`	`(project_id, workspace_id, instance_id)`	Get an instance

client.keys

Method	Signature	Description
`list`	`(project_id, environment_id, *, limit=20, cursor=None)`	List API keys
`create`	`(project_id, environment_id, **kwargs)`	Create an API key
`get`	`(project_id, environment_id, key_id)`	Get an API key
`rotate`	`(project_id, environment_id, key_id)`	Rotate an API key
`revoke`	`(project_id, environment_id, key_id)`	Revoke an API key
`disable`	`(project_id, environment_id, key_id)`	Disable an API key
`enable`	`(project_id, environment_id, key_id)`	Enable an API key

client.members

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List organization members
`invite`	`(**kwargs)`	Invite a new member
`set_role`	`(user_id, **kwargs)`	Set a member’s role
`remove`	`(user_id)`	Remove a member
`suspend`	`(user_id)`	Suspend a member
`reactivate`	`(user_id)`	Reactivate a member
`revoke_invitation`	`(user_id)`	Revoke a pending invitation

client.named_sets

Method	Signature	Description
`create`	`(project_id, **kwargs)`	Create a named set
`list`	`(project_id, *, limit=20, cursor=None)`	List named sets
`get`	`(project_id, named_set_id)`	Get a named set
`update`	`(project_id, named_set_id, **kwargs)`	Update a named set
`delete`	`(project_id, named_set_id)`	Delete a named set
`usage`	`(project_id, named_set_id)`	Get usage information

client.notifications

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List notifications
`read`	`(notification_id)`	Mark as read
`unread`	`(notification_id)`	Mark as unread

client.org

Method	Signature	Description
`get`	`()`	Get organization details
`update`	`(**kwargs)`	Update organization
`get_settings`	`()`	Get organization settings
`update_settings`	`(**kwargs)`	Update organization settings
`get_ai_policy`	`()`	Get automation policy
`update_ai_policy`	`(**kwargs)`	Update automation policy
`transfer_ownership`	`(**kwargs)`	Initiate ownership transfer
`accept_transfer`	`(transfer_id)`	Accept an ownership transfer
`cancel_transfer`	`(transfer_id)`	Cancel an ownership transfer
`get_transfer`	`()`	Get pending transfer details

client.projects

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List projects
`create`	`(**kwargs)`	Create a project
`get`	`(project_id)`	Get a project
`update`	`(project_id, **kwargs)`	Update a project
`archive`	`(project_id)`	Archive a project
`delete`	`(project_id)`	Delete a project
`list_members`	`(project_id, *, limit=20, cursor=None)`	List project members
`add_member`	`(project_id, **kwargs)`	Add a member
`remove_member`	`(project_id, assignment_id)`	Remove a member
`update_member`	`(project_id, assignment_id, **kwargs)`	Update a member’s role

client.service_accounts

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List service accounts
`create`	`(**kwargs)`	Create a service account
`update`	`(account_id, **kwargs)`	Update a service account
`disable`	`(account_id)`	Disable a service account
`enable`	`(account_id)`	Enable a service account

client.templates

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List templates
`get`	`(slug)`	Get a template
`fork`	`(slug, **kwargs)`	Fork a template into a project

client.users

Method	Signature	Description
`me`	`()`	Get current user profile
`organizations`	`()`	List user’s organizations

client.webhooks

Method	Signature	Description
`list`	`(project_id, *, limit=20, cursor=None)`	List project webhooks
`create`	`(project_id, **kwargs)`	Create a webhook
`update`	`(project_id, webhook_id, **kwargs)`	Update a webhook
`delete`	`(project_id, webhook_id)`	Delete a webhook
`rotate_secret`	`(project_id, webhook_id)`	Rotate signing secret
`deliveries`	`(project_id, webhook_id, *, limit=20, cursor=None)`	List deliveries
`list_org`	`(*, limit=20, cursor=None)`	List organization webhooks
`create_org`	`(**kwargs)`	Create an organization webhook

client.workspaces

Method	Signature	Description
`list`	`(*, limit=20, cursor=None)`	List workspaces
`create`	`(**kwargs)`	Create a workspace
`get`	`(workspace_id)`	Get a workspace
`update`	`(workspace_id, **kwargs)`	Update a workspace
`archive`	`(workspace_id)`	Archive a workspace
`delete`	`(workspace_id)`	Delete a workspace
`list_members`	`(workspace_id, *, limit=20, cursor=None)`	List workspace members
`add_member`	`(workspace_id, **kwargs)`	Add a member
`remove_member`	`(workspace_id, assignment_id)`	Remove a member

Pagination

All list methods use cursor-based pagination with a default limit of 20.

# Fetch all pages
all_items = []
result = client.projects.list(limit=50)
all_items.extend(result["items"])

while result.get("cursor"):
    result = client.projects.list(limit=50, cursor=result["cursor"])
    all_items.extend(result["items"])

Response Models

Top-level methods return typed response models. Most resource namespace methods return dict, except evaluations which returns typed models. The full list of exported models from vbos.models:

EvaluationResult, EvaluationListItem, PaginatedEvaluationResult, EvaluationRecord, EvaluationDetailResult, ReplayResult, Boundary, BoundaryList, BoundaryVersion, BoundaryVersionList, BoundaryDiff, Deployment, DeploymentList, ActiveDeployment, CertificationRun, CertificationList, CertificationReport, CertificationModel, CertificationModelList, CertificationModelVersion, Project, ProjectList, ProjectMember, ProjectMemberList, Environment, EnvironmentList, Template, TemplateList, ForkResult, Organization, OrgSettings, AIPolicy, OwnershipTransfer, Member, MemberList, APIKey, APIKeyList, APIKeyCreated, ServiceAccount, ServiceAccountList, Webhook, WebhookList, WebhookCreated, WebhookDelivery, WebhookDeliveryList, AssertionRateResult, DeferralRateResult, EvaluationSummary, FailureReason, FailureReasonResult, LatencyResult, AuditLogEntry, AuditLogList, AuditExportJob, AuditArtifactResult, UsageSummary, Subscription, Invoice, InvoiceList, Flow, FlowList, FlowVersion, FlowVersionList, FlowExecution, FlowExecutionList, FlowTemplate, FlowTemplateList, DryRunResult, AlertRule, AlertRuleList, Connector, ConnectorList, ConnectionTestResult, GatherResult, GatherList, ConnectorSchedule, ConnectorProvider, ConnectorProviderList, NamedSet, NamedSetList, NamedSetUsage, GovernedWorkspace, GovernedWorkspaceList, GovernedWorkspaceVersion, GovernedWorkspaceInstance, Notification, NotificationList, DeletionStatus, DataExport, DataExportList, Workspace, WorkspaceList, WorkspaceMember, WorkspaceMemberList, UserProfile, UserOrganization, UserOrganizationList, AdmissibilityResult, PredicateResult, ProhibitionsResult