openapi: 3.0.3
info:
  title: WarpStream Management ACLs Virtual Clusters API
  description: 'REST API for programmatically managing all aspects of the WarpStream control plane, including workspaces, virtual clusters, topics, ACLs, pipelines, agent pools, and BYOC deployments. All requests are issued as POST or GET requests with JSON payloads and authenticated via the warpstream-api-key header using Application Keys, Agent Keys, or Account Keys depending on the scope of resources being managed.

    '
  version: 1.0.0
  contact:
    url: https://docs.warpstream.com/warpstream/reference/api-reference
  license:
    name: WarpStream Terms of Service
    url: https://www.warpstream.com/terms-of-service
servers:
- url: https://api.warpstream.com
  description: WarpStream Management API
security:
- ApiKeyAuth: []
tags:
- name: Virtual Clusters
  description: Manage Kafka-compatible virtual clusters
paths:
  /api/v1/list_virtual_clusters:
    get:
      operationId: listVirtualClusters
      summary: List Virtual Clusters
      description: Returns all virtual clusters in the authenticated workspace.
      tags:
      - Virtual Clusters
      responses:
        '200':
          description: List of virtual clusters
          content:
            application/json:
              schema:
                type: object
                properties:
                  virtual_clusters:
                    type: array
                    items:
                      $ref: '#/components/schemas/VirtualCluster'
  /api/v1/create_virtual_cluster:
    post:
      operationId: createVirtualCluster
      summary: Create Virtual Cluster
      description: 'Creates a new virtual cluster. A new agent key is automatically created with every new virtual cluster.

        '
      tags:
      - Virtual Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - virtual_cluster_name
              - virtual_cluster_type
              - virtual_cluster_region
              - virtual_cluster_cloud_provider
              - virtual_cluster_tier
              properties:
                virtual_cluster_name:
                  type: string
                  description: Name for the cluster
                virtual_cluster_type:
                  type: string
                  enum:
                  - byoc
                  - byoc_data_lake
                  - byoc_schema_registry
                  description: Type of virtual cluster
                virtual_cluster_region:
                  type: string
                  description: Cloud region (e.g., us-east-1)
                virtual_cluster_cloud_provider:
                  type: string
                  description: Cloud provider (e.g., aws, gcp, azure)
                virtual_cluster_tier:
                  type: string
                  description: Cluster tier (e.g., dev, prod)
            example:
              virtual_cluster_name: my-cluster
              virtual_cluster_type: byoc
              virtual_cluster_region: us-east-1
              virtual_cluster_cloud_provider: aws
              virtual_cluster_tier: dev
      responses:
        '200':
          description: Created virtual cluster details
          content:
            application/json:
              schema:
                type: object
                properties:
                  virtual_cluster_id:
                    type: string
                  virtual_cluster_name:
                    type: string
                  agent_pool_id:
                    type: string
                  agent_pool_name:
                    type: string
                  agent_key:
                    $ref: '#/components/schemas/ApiKey'
                  bootstrap_url:
                    type: string
  /api/v1/delete_virtual_cluster:
    post:
      operationId: deleteVirtualCluster
      summary: Delete Virtual Cluster
      description: 'Permanently deletes a virtual cluster and all its data. Both virtual_cluster_id and virtual_cluster_name are required as a confirmation safeguard. This operation cannot be undone.

        '
      tags:
      - Virtual Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - virtual_cluster_id
              - virtual_cluster_name
              properties:
                virtual_cluster_id:
                  type: string
                  description: ID of the cluster to delete
                virtual_cluster_name:
                  type: string
                  description: Name of the cluster (confirmation safeguard)
            example:
              virtual_cluster_id: vci_1d4930d7_8e6d_4ad9_b27a_654ed4aaa3ee
              virtual_cluster_name: my-cluster
      responses:
        '200':
          description: Deletion successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
components:
  schemas:
    ApiKey:
      type: object
      properties:
        id:
          type: string
          description: API key identifier
        name:
          type: string
          description: Human-readable key name (prefixed with akn_)
        key:
          type: string
          description: The actual secret key value
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
        access_grants:
          type: array
          items:
            $ref: '#/components/schemas/AccessGrant'
    EmptyResponse:
      type: object
      description: Empty JSON object indicating success
      additionalProperties: false
    VirtualCluster:
      type: object
      properties:
        id:
          type: string
          description: Unique cluster identifier
        agent_pool_id:
          type: string
          description: Associated agent pool ID
        agent_pool_name:
          type: string
          description: Agent pool display name
        name:
          type: string
          description: Cluster name
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
        type:
          type: string
          enum:
          - byoc
          - byoc_data_lake
          - byoc_schema_registry
          description: Cluster type
        region:
          type: string
          description: Cloud region (e.g., us-east-1)
        cloud_provider:
          type: string
          description: Cloud provider (e.g., aws, gcp, azure)
        bootstrap_url:
          type: string
          description: Kafka bootstrap connection endpoint
        agent_keys:
          type: array
          items:
            $ref: '#/components/schemas/ApiKey'
    AccessGrant:
      type: object
      description: Permission grant for an API key
      properties:
        principal_kind:
          type: string
          enum:
          - application
          - agent
          description: Type of principal
        resource_kind:
          type: string
          enum:
          - '*'
          - virtual_cluster
          description: Kind of resource the grant applies to
        resource_id:
          type: string
          description: Specific resource ID or '*' for all resources
        workspace_id:
          type: string
          description: Workspace ID, required when using an account key
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: warpstream-api-key
      description: 'WarpStream API key. Three key types are supported: Application Keys (manage workspace-specific resources), Agent Keys (scoped to a specific virtual cluster), and Account Keys (manage account-level resources such as workspaces and users).

        '
externalDocs:
  description: WarpStream API Reference Documentation
  url: https://docs.warpstream.com/warpstream/reference/api-reference