openapi: 3.1.0
info:
  title: WunderGraph Cosmo Platform Analytics Namespaces API
  description: The WunderGraph Cosmo Platform API provides programmatic access to manage federated GraphQL architectures at scale. It powers the Cosmo CLI (wgc) and Cosmo Studio, enabling management of federated graphs, subgraphs, namespaces, schema contracts, feature flags, router configurations, and API keys. The API uses Connect-RPC protocol with HTTP/JSON support. Cosmo is the open-source alternative to Apollo GraphOS for full lifecycle GraphQL federation management including schema registry, composition checks, analytics, metrics, tracing, and routing.
  version: 1.0.0
  contact:
    name: WunderGraph
    url: https://wundergraph.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://cosmo-cp.wundergraph.com
  description: WunderGraph Cosmo Cloud Control Plane
tags:
- name: Namespaces
  description: Manage namespaces for organizing graphs and subgraphs.
paths:
  /v1/namespaces:
    get:
      operationId: listNamespaces
      summary: WunderGraph List namespaces
      description: Lists all namespaces within the organization. Namespaces provide logical isolation for federated graphs, subgraphs, and other resources.
      tags:
      - Namespaces
      security:
      - apiKey: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  namespaces:
                    type: array
                    items:
                      $ref: '#/components/schemas/Namespace'
    post:
      operationId: createNamespace
      summary: WunderGraph Create a namespace
      description: Creates a new namespace within the organization for organizing federated graphs and subgraphs.
      tags:
      - Namespaces
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the namespace to create.
      responses:
        '200':
          description: Namespace created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/namespaces/{name}:
    delete:
      operationId: deleteNamespace
      summary: WunderGraph Delete a namespace
      description: Deletes a namespace and all associated resources including federated graphs and subgraphs.
      tags:
      - Namespaces
      security:
      - apiKey: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: The name of the namespace to delete.
      responses:
        '200':
          description: Namespace deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/namespaces/{name}/rename:
    post:
      operationId: renameNamespace
      summary: WunderGraph Rename a namespace
      description: Renames an existing namespace.
      tags:
      - Namespaces
      security:
      - apiKey: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: The current name of the namespace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newName
              properties:
                newName:
                  type: string
                  description: The new name for the namespace.
      responses:
        '200':
          description: Namespace renamed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
components:
  schemas:
    OperationResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the operation was successful.
        message:
          type: string
          description: A human-readable response message.
    Namespace:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the namespace.
        name:
          type: string
          description: The name of the namespace.
        createdAt:
          type: string
          format: date-time
          description: When the namespace was created.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key for authenticating with the Cosmo Platform API. Obtain via Cosmo Studio or wgc CLI. Set as COSMO_API_KEY environment variable.