WunderGraph Cosmo Platform API

openapi: 3.1.0
info:
  title: WunderGraph Cosmo Platform 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
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'
  /v1/federated-graphs:
    get:
      operationId: listFederatedGraphs
      summary: WunderGraph List federated graphs
      description: >-
        Lists all federated graphs in the organization, optionally filtered by
        namespace. Federated graphs represent the composed supergraph made up of
        multiple subgraphs.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      parameters:
        - name: namespace
          in: query
          schema:
            type: string
          description: Filter by namespace name.
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results to return.
        - name: offset
          in: query
          schema:
            type: integer
          description: Number of results to skip.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  graphs:
                    type: array
                    items:
                      $ref: '#/components/schemas/FederatedGraph'
    post:
      operationId: createFederatedGraph
      summary: WunderGraph Create a federated graph
      description: >-
        Creates a new federated graph. A federated graph is composed from one or
        more subgraphs selected by label matchers.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - routingUrl
              properties:
                name:
                  type: string
                  description: The name of the federated graph.
                namespace:
                  type: string
                  description: The namespace for the graph. Defaults to "default".
                routingUrl:
                  type: string
                  format: uri
                  description: The URL where the router is hosted.
                labelMatchers:
                  type: array
                  items:
                    type: string
                  description: >-
                    Label matchers to select subgraphs for composition
                    (e.g., "team=backend").
                admissionWebhookUrl:
                  type: string
                  format: uri
                  description: URL of the admission webhook for schema validation.
                readme:
                  type: string
                  description: A readme description for the federated graph.
      responses:
        '200':
          description: Federated graph created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/federated-graphs/{name}:
    get:
      operationId: getFederatedGraph
      summary: WunderGraph Get a federated graph
      description: Retrieves details of a specific federated graph by name.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the federated graph.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the graph.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederatedGraph'
    put:
      operationId: updateFederatedGraph
      summary: WunderGraph Update a federated graph
      description: >-
        Updates the configuration of an existing federated graph, including its
        routing URL, label matchers, or admission webhook.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the federated graph to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                  description: The namespace of the graph.
                routingUrl:
                  type: string
                  format: uri
                  description: The new routing URL.
                labelMatchers:
                  type: array
                  items:
                    type: string
                  description: Updated label matchers for subgraph selection.
                admissionWebhookUrl:
                  type: string
                  format: uri
                  description: Updated admission webhook URL.
                readme:
                  type: string
                  description: Updated readme content.
      responses:
        '200':
          description: Federated graph updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
    delete:
      operationId: deleteFederatedGraph
      summary: WunderGraph Delete a federated graph
      description: >-
        Deletes a federated graph and its associated configuration from the
        control plane.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the federated graph to delete.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the graph.
      responses:
        '200':
          description: Federated graph deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/federated-graphs/{name}/fetch:
    get:
      operationId: fetchFederatedGraphSDL
      summary: WunderGraph Fetch federated graph SDL
      description: >-
        Downloads the latest valid Schema Definition Language (SDL) of a
        federated graph and all its subgraphs from the control plane.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the federated graph.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the graph.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  sdl:
                    type: string
                    description: The composed GraphQL SDL of the federated graph.
                  subgraphs:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        sdl:
                          type: string
  /v1/federated-graphs/{name}/changelog:
    get:
      operationId: getFederatedGraphChangelog
      summary: WunderGraph Get federated graph changelog
      description: >-
        Retrieves the composition changelog for a federated graph showing schema
        changes over time.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the federated graph.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the graph.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  changelog:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChangelogEntry'
  /v1/federated-graphs/{name}/move:
    post:
      operationId: moveFederatedGraph
      summary: WunderGraph Move a federated graph to another namespace
      description: Moves a federated graph from one namespace to another.
      tags:
        - Federated Graphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the federated graph to move.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - newNamespace
              properties:
                namespace:
                  type: string
                  description: The current namespace of the graph.
                newNamespace:
                  type: string
                  description: The target namespace to move the graph to.
      responses:
        '200':
          description: Federated graph moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/subgraphs:
    get:
      operationId: listSubgraphs
      summary: WunderGraph List subgraphs
      description: >-
        Lists all subgraphs in the organization, optionally filtered by
        namespace. Subgraphs are isolated GraphQL schemas that compose into
        federated graphs.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: namespace
          in: query
          schema:
            type: string
          description: Filter by namespace name.
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results to return.
        - name: offset
          in: query
          schema:
            type: integer
          description: Number of results to skip.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  subgraphs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subgraph'
    post:
      operationId: createSubgraph
      summary: WunderGraph Create a subgraph
      description: >-
        Creates a new subgraph within the Cosmo platform. Subgraphs are
        isolated GraphQL schemas that can be independently deployed and
        managed, providing modularity and scalability to your GraphQL APIs.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - routingUrl
              properties:
                name:
                  type: string
                  description: The name of the subgraph.
                namespace:
                  type: string
                  description: The namespace for the subgraph.
                routingUrl:
                  type: string
                  format: uri
                  description: >-
                    The URL where the subgraph service is hosted for routing
                    requests.
                labels:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      value:
                        type: string
                  description: >-
                    Labels for matching subgraphs to federated graphs
                    (e.g., team=backend).
                subscriptionUrl:
                  type: string
                  format: uri
                  description: >-
                    URL for WebSocket-based GraphQL subscriptions if different
                    from the routing URL.
                subscriptionProtocol:
                  type: string
                  enum:
                    - ws
                    - sse
                    - sse_post
                  description: The subscription transport protocol.
                readme:
                  type: string
                  description: A readme description for the subgraph.
      responses:
        '200':
          description: Subgraph created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/subgraphs/{name}:
    get:
      operationId: getSubgraph
      summary: WunderGraph Get a subgraph
      description: Retrieves details of a specific subgraph by name.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the subgraph.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the subgraph.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subgraph'
    put:
      operationId: updateSubgraph
      summary: WunderGraph Update a subgraph
      description: >-
        Updates the configuration of an existing subgraph, such as its routing
        URL, labels, or subscription settings.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the subgraph to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                  description: The namespace of the subgraph.
                routingUrl:
                  type: string
                  format: uri
                  description: The updated routing URL.
                labels:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      value:
                        type: string
                  description: Updated labels for the subgraph.
                subscriptionUrl:
                  type: string
                  format: uri
                  description: Updated subscription URL.
                subscriptionProtocol:
                  type: string
                  enum:
                    - ws
                    - sse
                    - sse_post
                  description: Updated subscription protocol.
                readme:
                  type: string
                  description: Updated readme content.
      responses:
        '200':
          description: Subgraph updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
    delete:
      operationId: deleteSubgraph
      summary: WunderGraph Delete a subgraph
      description: >-
        Deletes a subgraph from the platform. This will trigger recomposition
        of any federated graphs that included this subgraph.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the subgraph to delete.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the subgraph.
      responses:
        '200':
          description: Subgraph deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/subgraphs/{name}/publish:
    post:
      operationId: publishSubgraph
      summary: WunderGraph Publish a subgraph schema
      description: >-
        Publishes a new schema for the specified subgraph. This triggers
        composition checks and updates the federated graphs that include
        this subgraph.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the subgraph to publish.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - schema
              properties:
                namespace:
                  type: string
                  description: The namespace of the subgraph.
                schema:
                  type: string
                  description: The GraphQL schema SDL content for the subgraph.
      responses:
        '200':
          description: Schema published successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  compositionErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        federatedGraphName:
                          type: string
                  hasChanged:
                    type: boolean
                    description: Whether the schema has changed from the previous version.
  /v1/subgraphs/{name}/check:
    post:
      operationId: checkSubgraph
      summary: WunderGraph Check a subgraph schema
      description: >-
        Checks a subgraph schema for breaking changes and composition errors
        across all connected federated graphs without publishing. Used for
        CI/CD validation.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the subgraph to check.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - schema
              properties:
                namespace:
                  type: string
                  description: The namespace of the subgraph.
                schema:
                  type: string
                  description: The GraphQL schema SDL to validate.
      responses:
        '200':
          description: Check completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  breakingChanges:
                    type: array
                    items:
                      type: object
                      properties:
                        changeType:
                          type: string
                        message:
                          type: string
                        path:
                          type: string
                  compositionErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        federatedGraphName:
                          type: string
                  nonBreakingChanges:
                    type: array
                    items:
                      type: object
                      properties:
                        changeType:
                          type: string
                        message:
                          type: string
                        path:
                          type: string
  /v1/subgraphs/{name}/fetch:
    get:
      operationId: fetchSubgraphSDL
      summary: WunderGraph Fetch subgraph SDL
      description: >-
        Downloads the latest valid Schema Definition Language (SDL) of a
        specific subgraph.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the subgraph.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the subgraph.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  sdl:
                    type: string
                    description: The GraphQL SDL of the subgraph.
  /v1/subgraphs/{name}/move:
    post:
      operationId: moveSubgraph
      summary: WunderGraph Move a subgraph to another namespace
      description: Moves a subgraph from one namespace to another.
      tags:
        - Subgraphs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the subgraph to move.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - newNamespace
              properties:
                namespace:
                  type: string
                  description: The current namespace of the subgraph.
                newNamespace:
                  type: string
                  description: The target namespace.
      responses:
        '200':
          description: Subgraph moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/monographs:
    get:
      operationId: listMonographs
      summary: WunderGraph List monographs
      description: >-
        Lists all monographs in the organization. A monograph is a graph with
        GraphQL Federation disabled, limited to a single subgraph.
      tags:
        - Monographs
      security:
        - apiKey: []
      parameters:
        - name: namespace
          in: query
          schema:
            type: string
          description: Filter by namespace name.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  monographs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Monograph'
    post:
      operationId: createMonograph
      summary: WunderGraph Create a monograph
      description: >-
        Creates a new monograph (non-federated, single subgraph graph) in the
        Cosmo platform.
      tags:
        - Monographs
      security:
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - routingUrl
                - graphUrl
              properties:
                name:
                  type: string
                  description: The name of the monograph.
                namespace:
                  type: string
                  description: The namespace for the monograph.
                routingUrl:
                  type: string
                  format: uri
                  description: The URL where the router is hosted.
                graphUrl:
                  type: string
                  format: uri
                  description: The URL of the GraphQL service.
                admissionWebhookUrl:
                  type: string
                  format: uri
                  description: URL of the admission webhook.
                readme:
                  type: string
                  description: A readme description for the monograph.
      responses:
        '200':
          description: Monograph created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/monographs/{name}:
    put:
      operationId: updateMonograph
      summary: WunderGraph Update a monograph
      description: Updates the configuration of an existing monograph.
      tags:
        - Monographs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the monograph to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                routingUrl:
                  type: string
                  format: uri
                graphUrl:
                  type: string
                  format: uri
                admissionWebhookUrl:
                  type: string
                  format: uri
                readme:
                  type: string
      responses:
        '200':
          description: Monograph updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
    delete:
      operationId: deleteMonograph
      summary: WunderGraph Delete a monograph
      description: Deletes a monograph from the platform.
      tags:
        - Monographs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the monograph to delete.
        - name: namespace
          in: query
          schema:
            type: string
          description: The namespace of the monograph.
      responses:
        '200':
          description: Monograph deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /v1/monographs/{name}/publish:
    post:
      operationId: publishMonograph
      summary: WunderGraph Publish a monograph schema
      description: Publishes a new schema for the specified monograph.
      tags:
        - Monographs
      security:
        - apiKey: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The name of the monograph to publish.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - schema
              properties:
                namespace:
                  type: string
                schema:
                  type: string
                  description: The GraphQL schema SDL content.
      responses:
        '200':
          description: Schema published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
  /

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wundergraph/refs/heads/main/openapi/wundergraph-cosmo-platform-openapi.yml