openapi: 3.1.0
info:
  title: WunderGraph Cosmo Platform Analytics Subgraphs 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: 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:
    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
    OperationResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the operation was successful.
        message:
          type: string
          description: A human-readable response message.
  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.