VentStream Cloud exposes a REST/JSON API under /v1. ventstreamctl, the
dashboard, and approved automation use the same organization-scoped resource and
operation model.
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.
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.
