Skip to main content
VentStream Cloud exposes a REST/JSON API under /v1. The hosted control plane’s base URL is https://api.ventstream.dev. ventstreamctl, the dashboard, and approved automation use the same organization-scoped resource and operation model. For example, listing an organization’s environments:

​
Contract rules

  • Human requests use short-lived OIDC or first-party bearer tokens.
  • Automation uses a configured OIDC workload provider and scoped service account.
  • Collection endpoints use opaque cursor pagination and bounded limits.
  • Retryable mutations require Idempotency-Key.
  • Concurrent mutations require the current strong ETag in If-Match.
  • Lifecycle and configuration actions return durable operations rather than waiting synchronously for an agent.
  • Every response and audit event carries a request identifier.
  • Errors contain stable codes and safe messages, never database details or secrets.

​
Main resources

​
CLI and API coverage

ventstreamctl covers account authentication, organizations, environments, pipelines, configuration revisions, deployments, enrollment, identities, and durable operations. The current CLI does not expose every V1 administration resource. Use the dashboard or API for:
  • Organization invitations and invite acceptance
  • Role bindings and membership revocation
  • Service accounts
  • Organization settings and billing metadata
  • Organization audit-event queries
These endpoints use the same bearer authentication, permission checks, tenant isolation, If-Match, idempotency, pagination, and safe error envelope described above. Do not build automation from undocumented database access.
Legacy: enrollment grants. Enrollment grants are returned once with Cache-Control: no-store. They are not generic API keys and must never be written to logs or an idempotency response ledger. Agent keys (vsa1.) are the current mechanism for attaching engines — see Managed mode.
See CLI administration for the supported operator workflow.