openapi: 3.1.0
info:
  title: WunderGraph Cosmo Platform Analytics Feature Flags 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: Feature Flags
  description: Manage feature flags for gradual rollout of graph changes.
paths:
  /v1/feature-flags:
    get:
      operationId: listFeatureFlags
      summary: WunderGraph List feature flags
      description: Lists all feature flags in the organization for managing gradual rollout of graph changes.
      tags:
      - Feature Flags
      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:
                  featureFlags:
                    type: array
                    items:
                      $ref: '#/components/schemas/FeatureFlag'
    post:
      operationId: createFeatureFlag
      summary: WunderGraph Create a feature flag
      description: Creates a new feature flag for enabling gradual rollout of feature subgraphs to federated graphs.
      tags:
      - Feature Flags
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - featureSubgraphNames
              properties:
                name:
                  type: string
                  description: The name of the feature flag.
                namespace:
                  type: string
                  description: The namespace for the feature flag.
                featureSubgraphNames:
                  type: array
                  items:
                    type: string
                  description: List of feature subgraph names to associate with this flag.
                isEnabled:
                  type: boolean
                  description: Whether the feature flag is enabled.
                labels:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      value:
                        type: string
                  description: Labels to match federated graphs.
      responses:
        '200':
          description: Feature flag created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
components:
  schemas:
    FeatureFlag:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the feature flag.
        name:
          type: string
          description: The name of the feature flag.
        namespace:
          type: string
          description: The namespace the feature flag belongs to.
        isEnabled:
          type: boolean
          description: Whether the feature flag is currently enabled.
        featureSubgraphNames:
          type: array
          items:
            type: string
          description: Associated feature subgraph names.
        labels:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
        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.