openapi: 3.1.0
info:
  title: WunderGraph Cosmo Platform Analytics Router 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: Router
  description: Manage router configuration and authentication tokens.
paths:
  /v1/router/compose:
    post:
      operationId: composeRouterConfig
      summary: WunderGraph Compose router configuration
      description: Generates a router execution configuration for a federated graph. The router configuration is used by the Cosmo Router to serve the composed federated graph.
      tags:
      - Router
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - federatedGraphName
              properties:
                federatedGraphName:
                  type: string
                  description: The name of the federated graph to compose.
                namespace:
                  type: string
                  description: The namespace of the graph.
      responses:
        '200':
          description: Router configuration generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: object
                    description: The composed router execution configuration.
  /v1/router/tokens:
    get:
      operationId: listRouterTokens
      summary: WunderGraph List router tokens
      description: Lists all router tokens for a federated graph. Router tokens are used to authenticate Cosmo Router instances with the control plane.
      tags:
      - Router
      security:
      - apiKey: []
      parameters:
      - name: federatedGraphName
        in: query
        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:
                  tokens:
                    type: array
                    items:
                      $ref: '#/components/schemas/RouterToken'
    post:
      operationId: createRouterToken
      summary: WunderGraph Create a router token
      description: Creates a new router token for authenticating a Cosmo Router instance with the control plane.
      tags:
      - Router
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - federatedGraphName
              - tokenName
              properties:
                federatedGraphName:
                  type: string
                  description: The name of the federated graph.
                namespace:
                  type: string
                  description: The namespace of the graph.
                tokenName:
                  type: string
                  description: A name for the router token.
      responses:
        '200':
          description: Token created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: The generated router token value.
components:
  schemas:
    RouterToken:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the router token.
        name:
          type: string
          description: The name of the router token.
        createdAt:
          type: string
          format: date-time
          description: When the token was created.
        lastUsedAt:
          type: string
          format: date-time
          description: When the token was last used.
  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.