WunderGraph Subgraphs API

openapi: 3.2.0
info:
  title: WunderGraph Cosmo Platform Subgraphs API
  description: The WunderGraph Cosmo Platform API provides programmatic access to manage federated GraphQL architectures at scale.
  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: Subgraphs
  description: Manage subgraphs - isolated GraphQL schemas that compose into federated graphs.
paths:
  /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'
components:
  schemas:
    OperationResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the operation was successful.
        message:
          type: string
          description: A human-readable response message.
    Subgraph:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the subgraph.
        name:
          type: string
          description: The name of the subgraph.
        namespace:
          type: string
          description: The namespace the subgraph belongs to.
        routingUrl:
          type: string
          format: uri
          description: The URL where the subgraph service is hosted.
        labels:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
          description: Labels attached to the subgraph.
        subscriptionUrl:
          type: string
          format: uri
          description: URL for GraphQL subscriptions.
        subscriptionProtocol:
          type: string
          enum:
          - ws
          - sse
          - sse_post
          description: The subscription transport protocol.
        lastPublishedAt:
          type: string
          format: date-time
          description: When the schema was last published.
        readme:
          type: string
          description: Readme description of the subgraph.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  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.
x-authored-by: API Evangelist
x-modeled-from: documentation
x-provenance:
  method: modeled
  authored_by: API Evangelist
  modeled_from: https://cosmo-docs.wundergraph.com/
  provider_published: false
  note: Modeled by API Evangelist from WunderGraph's public Cosmo documentation. The provider does not publish a REST OpenAPI. The real control-plane interface is Connect-RPC, defined in WunderGraph's own platform.proto — see grpc/ for the verbatim first-party contract, which is authoritative where this document and the proto disagree.
  verified: '2026-08-03'
  evidence:
  - url: https://cosmo-cp.wundergraph.com/openapi.json
    status: 404
    note: no provider-published OpenAPI at the control-plane host
  - url: https://cosmo-cp.wundergraph.com/v1/analytics
    status: 404
    note: REST path modeled in this document does not resolve
  - url: https://cosmo-cp.wundergraph.com/wg.cosmo.platform.v1.PlatformService/GetFederatedGraphs
    status: 200
    method: POST
    note: the surface that does exist — Connect-RPC, not REST