API fundamentals
Choose the service endpoint, authenticate requests and apply organization and workspace scope.
Use the service base URL shown by your deployment and the authentication requirements of the operation you call. Product references describe resource paths relative to that service and workspace.
Service paths
| Service | Base path | Purpose |
|---|---|---|
| Account | /api/v1/account | Authentication, organization security, identities and workspaces. |
| Secret | /api/v1/secret | Vault namespaces, secrets and permissions. |
| VegaFlow | /api/v1/vegaflow | Connections, compute, QuickFlows and workflow resources. |
| VegaGraph | /api/v1/vegagraph | Types, entities, aspects, contexts, search and lineage. |
VegaDB SQL clients use the warehouse's PostgreSQL protocol endpoint. Follow Connect to VegaDB for its connection settings and client examples.
Authentication
| Scheme | Use |
|---|---|
| Bearer token | An authenticated user token accepted by the operation. |
| API key | An authorized service-principal credential where the operation supports it. |
Use the accepted scheme and its documented header. Do not send both credentials by default. Keep credentials in environment-backed or managed secret storage, and grant the identity only the required resource permissions.
Tenant scope
Most product resource paths include organization and workspace IDs:
{service-base}/orgs/{org_id}/workspaces/{workspace_id}/...Organization administration can stop at org_id; authentication operations can be unscoped. The workspace must belong to the selected organization. A valid credential does not bypass resource permissions or scope checks.
For example, listing VegaFlow connectors includes a second /vegaflow segment below the workspace:
curl --request GET \
--header "Authorization: Bearer $VEGALAKE_ACCESS_TOKEN" \
--header "Accept: application/json" \
"https://api.example.com/api/v1/vegaflow/orgs/org_01/workspaces/ws_01/vegaflow/connectors"Replace the example host and tenant IDs with your deployment values. See the VegaFlow API reference and VegaGraph API reference for resource-specific paths.
Requests and responses
Send Content-Type: application/json when an operation defines a JSON body. Use required fields, enums and cross-field rules from its current schema. Pagination parameters and response envelopes vary by operation.
An accepted asynchronous request is not proof of completion. Retain the returned resource or run ID and inspect its state. Before replaying a failed mutation, check whether it already created a resource and whether the operation supplies an idempotency mechanism.
Errors
| Response | First check |
|---|---|
400 / 422 | Required fields, types, enums and configuration constraints. |
401 | Accepted authentication scheme and credential validity. |
403 / 404 | Organization/workspace IDs and collection or instance permissions. |
409 | Name/version conflicts, dependencies and lifecycle state. |
429 | Server retry guidance and request rate. |
5xx | Resource state before retrying a mutation. |
Preserve the request ID and structured error when available. Redact credentials and sensitive payloads before sharing diagnostic details. See platform troubleshooting.