Control Plane API

REST surface for automating Cube Cloud deployments, environments, JWT issuance, and audit log export.

Control Plane API enables programmatic management of deployments and environments in Cube Cloud. You can use it to list deployments, manage environments, generate JWT tokens for accessing Core Data APIs, and export audit log events.

Control Plane API is only available in Cube Cloud.

Prerequisites

Authentication

Control Plane API uses API key authentication. Include your API key in the Authorization header with the Bearer prefix:

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments

Error handling

In case of an error, Control Plane API returns a JSON object with an error property:

{
  "error": "Error message"
}

Pagination

Endpoints that return lists support pagination using offset and limit query parameters:

Parameter	Description
offset	Number of items to skip. Default: 0
limit	Maximum number of items to return. Default: 20

Paginated responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 42
  }
}

Reference

/api/v1/deployments

Send a GET request to list all deployments accessible to the authenticated user.

Query parameters:

Parameter	Description	Required
offset	Pagination offset	No
limit	Pagination limit	No

Example request:

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments"

Example response:

{
  "data": {
    "deployments": [
      {
        "id": "123",
        "name": "My Deployment",
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1
  }
}

/api/v1/deployments/{deployment_id}/environments

Send a GET request to list environments for a specific deployment.

Path parameters:

Parameter	Description
deployment_id	The deployment ID

Query parameters:

Parameter	Description	Required
type	Filter by environment type: production, staging, or development	No
offset	Pagination offset	No
limit	Pagination limit	No

Example request:

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments/123/environments"

Example response:

{
  "data": {
    "environments": [
      {
        "id": "456",
        "name": "Production",
        "type": "production",
        "api_credentials": {
          "rest": {
            "url": "https://example.cubecloud.dev/cubejs-api"
          },
          "sql": {
            "host": "example.sql.cubecloud.dev",
            "port": 5432
          }
        }
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1
  }
}

/api/v1/deployments/{deployment_id}/environments/{environment_id}/tokens-for-meta-sync

Send a POST request to create a JWT token for accessing the Metadata API. The generated token is scoped specifically to metadata endpoints (e.g., /v1/data-sources, /v1/entities) and cannot be used to query data via the REST (JSON) API. This makes it suitable for integrations such as data catalogs and lineage tools that only need to read data model metadata.

The security context you provide is embedded in the token and controls which parts of the data model are visible, following the same multi-tenancy rules as regular API tokens.

Path parameters:

Parameter	Description
deployment_id	The deployment ID
environment_id	The environment ID

Request body:

Property	Type	Description	Required
security_context	object	Security context to embed in the token. Controls data model visibility based on your multi-tenancy configuration.	Yes
expires_in	number	Token expiration time in seconds. Default: 86400 (24 hours)	No

Example request:

curl \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "security_context": {"tenant_id": "acme"},
    "expires_in": 3600
  }' \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/deployments/123/environments/456/tokens-for-meta-sync"

Example response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "created_at": "2024-01-15T10:30:00.000Z",
    "expires_at": "2024-01-15T11:30:00.000Z"
  }
}

/build/api/v1/deployments/{deployment_id}/branches/staging-environment

Send a PUT request to enable or disable a branch, i.e. to control whether its staging environment stays always active. Disabled (the default), a staging environment is only active while the branch is viewed in the Cube UI; enabled, it remains active and accessible regardless of user activity, and it is reported by /api/v1/deployments/{deployment_id}/environments as a staging environment.

Only shared branches can be enabled — personal development branches and the production branch are rejected.

Note the /build prefix: data model and branch endpoints are served by the build API.

Path parameters:

Parameter	Description
deployment_id	The deployment ID

Body parameters:

Parameter	Description	Required
enabled	true enables the branch, false disables it	Yes
branchName	Name of the branch to update	One of branchName or branchId
branchId	ID of the branch to update, as returned by GET /build/api/v1/deployments/{deployment_id}/branches	One of branchName or branchId

Example request:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branchName": "staging", "enabled": true}' \
  "https://YOUR_CUBE_CLOUD_HOST/build/api/v1/deployments/123/branches/staging-environment"

Example response:

{
  "data": {
    "id": 456,
    "name": "staging",
    "parentBranch": "main",
    "lastHash": "9f2c1ab",
    "isStagingEnvironmentEnabled": true
  }
}

The same operation is available in the CLI as cube data-model enable-branch / cube data-model disable-branch.

/api/v1/audit-logs/export

Send a GET request to export audit log events as a CSV file. This endpoint allows you to programmatically retrieve security-related events for compliance reviews, external log aggregation, or integration with SIEM tools.

Requires Audit Log to be enabled on the Enterprise plan. The authenticated user must have the AuditLogManage permission.

Query parameters:

Parameter	Description	Required
start	Start of the date range (ISO 8601 format, e.g., 2024-01-01)	No
end	End of the date range (ISO 8601 format, e.g., 2024-01-31)	No
search	Full-text search across event data	No
eventName	Filter by event type (e.g., Logged in)	No
userEmail	Filter by user email	No

The response is a CSV file streamed as an attachment.

Example request:

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit_log.csv \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/audit-logs/export?start=2024-01-01&end=2024-01-31"

Example request with filters:

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit_log.csv \
  "https://YOUR_CUBE_CLOUD_HOST/api/v1/audit-logs/export?start=2024-01-01&end=2024-01-31&eventName=Logged+in&userEmail=[e-mail]"