LaunchDarkly Relay Proxy

openapi: 3.1.0
info:
  title: LaunchDarkly Relay Proxy
  description: >-
    The LaunchDarkly Relay Proxy is a small Go application that connects
    to the LaunchDarkly streaming API and proxies that connection to SDK
    clients within an organization's network. It exposes endpoints for
    status monitoring, flag evaluation, and SDK streaming that mirror the
    LaunchDarkly service endpoints. Instead of each server making outbound
    connections to LaunchDarkly's streaming service, multiple servers
    connect to the local Relay Proxy which maintains a single upstream
    connection.
  version: '8.0'
  contact:
    name: LaunchDarkly Support
    url: https://support.launchdarkly.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: Relay Proxy Documentation
  url: https://launchdarkly.com/docs/sdk/relay-proxy
servers:
  - url: http://localhost:8030
    description: Default Relay Proxy instance
tags:
  - name: Client-Side Evaluation
    description: >-
      Flag evaluation endpoints for client-side and mobile SDKs using
      environment IDs or mobile keys for authentication.
  - name: Client-Side Streaming
    description: >-
      Server-Sent Events streaming endpoints for client-side and
      mobile SDKs to receive real-time flag updates.
  - name: PHP Polling
    description: >-
      Polling endpoints for PHP server-side SDKs which do not
      support streaming mode.
  - name: Server-Side Evaluation
    description: >-
      Flag evaluation endpoints for server-side SDKs using SDK keys
      for authentication.
  - name: Server-Side Streaming
    description: >-
      Server-Sent Events streaming endpoints for server-side SDKs
      to receive real-time flag updates.
  - name: Status
    description: >-
      Health and status monitoring endpoints for the Relay Proxy.
      No authentication is required for these endpoints.
paths:
  /status:
    get:
      operationId: getRelayProxyStatus
      summary: Get Relay Proxy status
      description: >-
        Returns the overall health status of the Relay Proxy and
        detailed connection status for each configured environment.
        No authentication is required. The top-level status is
        "healthy" if all environments are connected, or "degraded"
        if any environment is disconnected.
      tags:
        - Status
      responses:
        '200':
          description: >-
            Successful response containing the Relay Proxy status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelayProxyStatus'
  /sdk/evalx/contexts/{contextBase64}:
    get:
      operationId: evaluateAllFlagsForContext
      summary: Evaluate all flags for a context (GET)
      description: >-
        Evaluates all feature flags for the given context and returns
        the results. The context is provided as a base64-encoded JSON
        object in the URL path. Requires an SDK key in the
        Authorization header.
      tags:
        - Server-Side Evaluation
      security:
        - sdkKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ContextBase64'
      responses:
        '200':
          description: >-
            Successful response with all flag evaluations for
            the context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagEvaluations'
        '401':
          description: >-
            Unauthorized. The SDK key does not match any environment
            configured in the Relay Proxy.
        '503':
          description: >-
            Service unavailable. The Relay Proxy has not yet received
            flag data from LaunchDarkly for this environment.
  /sdk/evalx/context:
    report:
      operationId: evaluateAllFlagsForContextReport
      summary: Evaluate all flags for a context (REPORT)
      description: >-
        Evaluates all feature flags for the given context provided
        in the request body. Uses the REPORT HTTP method to support
        larger context payloads. Requires an SDK key in the
        Authorization header.
      tags:
        - Server-Side Evaluation
      security:
        - sdkKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationContext'
      responses:
        '200':
          description: >-
            Successful response with all flag evaluations for
            the context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagEvaluations'
        '401':
          description: >-
            Unauthorized. Invalid SDK key.
        '503':
          description: >-
            Service unavailable. Flag data not yet available.
  /sdk/evalx/{envId}/contexts/{contextBase64}:
    get:
      operationId: evaluateAllFlagsClientSide
      summary: Evaluate all flags for a client-side context (GET)
      description: >-
        Evaluates all client-side enabled feature flags for the given
        context. Uses the environment ID in the URL path for
        authentication.
      tags:
        - Client-Side Evaluation
      parameters:
        - $ref: '#/components/parameters/EnvironmentId'
        - $ref: '#/components/parameters/ContextBase64'
      responses:
        '200':
          description: >-
            Successful response with all client-side flag evaluations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagEvaluations'
        '401':
          description: >-
            Unauthorized. Invalid environment ID.
        '503':
          description: >-
            Service unavailable. Flag data not yet available.
  /sdk/evalx/{envId}/context:
    report:
      operationId: evaluateAllFlagsClientSideReport
      summary: Evaluate all flags for a client-side context (REPORT)
      description: >-
        Evaluates all client-side enabled feature flags for the given
        context provided in the request body. Uses the REPORT HTTP
        method for larger payloads.
      tags:
        - Client-Side Evaluation
      parameters:
        - $ref: '#/components/parameters/EnvironmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationContext'
      responses:
        '200':
          description: >-
            Successful response with all client-side flag evaluations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagEvaluations'
        '401':
          description: >-
            Unauthorized. Invalid environment ID.
        '503':
          description: >-
            Service unavailable. Flag data not yet available.
  /all:
    get:
      operationId: streamAllFlags
      summary: Stream all flag data (server-side)
      description: >-
        Establishes a Server-Sent Events (SSE) stream that delivers
        real-time flag data updates for server-side SDKs. Requires
        an SDK key in the Authorization header.
      tags:
        - Server-Side Streaming
      security:
        - sdkKeyAuth: []
      responses:
        '200':
          description: >-
            SSE stream delivering flag data updates.
          content:
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-Sent Events stream with put and patch events.
        '401':
          description: >-
            Unauthorized. Invalid SDK key.
        '503':
          description: >-
            Service unavailable. Flag data not yet available.
  /flags:
    get:
      operationId: streamFlagsOnly
      summary: Stream flag updates (server-side)
      description: >-
        Establishes a Server-Sent Events (SSE) stream that delivers
        only flag updates (not segments) for server-side SDKs.
      tags:
        - Server-Side Streaming
      security:
        - sdkKeyAuth: []
      responses:
        '200':
          description: >-
            SSE stream delivering flag updates.
          content:
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-Sent Events stream with flag events.
        '401':
          description: >-
            Unauthorized. Invalid SDK key.
        '503':
          description: >-
            Service unavailable.
  /eval/{envId}/{contextBase64}:
    get:
      operationId: streamClientSideEval
      summary: Stream evaluated flags (client-side)
      description: >-
        Establishes a Server-Sent Events (SSE) stream that delivers
        evaluated flag values for the given context to client-side SDKs.
      tags:
        - Client-Side Streaming
      parameters:
        - $ref: '#/components/parameters/EnvironmentId'
        - $ref: '#/components/parameters/ContextBase64'
      responses:
        '200':
          description: >-
            SSE stream delivering evaluated flag values.
          content:
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-Sent Events stream with evaluated flag data.
        '401':
          description: >-
            Unauthorized. Invalid environment ID.
        '503':
          description: >-
            Service unavailable. Flag data not yet available.
  /meval/{envId}:
    report:
      operationId: streamMobileEval
      summary: Stream evaluated flags (mobile)
      description: >-
        Establishes a Server-Sent Events (SSE) stream for mobile SDKs
        using the REPORT method. Requires a mobile key in the
        Authorization header.
      tags:
        - Client-Side Streaming
      parameters:
        - $ref: '#/components/parameters/EnvironmentId'
      security:
        - mobileKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationContext'
      responses:
        '200':
          description: >-
            SSE stream delivering evaluated flag values.
          content:
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-Sent Events stream with evaluated flag data.
        '401':
          description: >-
            Unauthorized. Invalid mobile key.
        '503':
          description: >-
            Service unavailable.
  /sdk/latest-all:
    get:
      operationId: getLatestAllFlags
      summary: Get latest all flags (PHP polling)
      description: >-
        Returns the latest flag data for PHP server-side SDKs that
        use polling mode instead of streaming. Requires an SDK key
        in the Authorization header.
      tags:
        - PHP Polling
      security:
        - sdkKeyAuth: []
      responses:
        '200':
          description: >-
            Successful response containing the latest flag data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagData'
        '401':
          description: >-
            Unauthorized. Invalid SDK key.
        '503':
          description: >-
            Service unavailable. Flag data not yet available.
components:
  securitySchemes:
    sdkKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Server-side SDK key for authenticating with the Relay Proxy.
    mobileKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Mobile SDK key for authenticating with the Relay Proxy.
  parameters:
    ContextBase64:
      name: contextBase64
      in: path
      required: true
      description: >-
        A base64-encoded JSON representation of the evaluation context.
      schema:
        type: string
    EnvironmentId:
      name: envId
      in: path
      required: true
      description: >-
        The client-side environment ID.
      schema:
        type: string
  schemas:
    RelayProxyStatus:
      type: object
      description: >-
        The overall status of the Relay Proxy and its environments.
      properties:
        status:
          type: string
          description: >-
            The overall health status of the Relay Proxy.
          enum:
            - healthy
            - degraded
        environments:
          type: object
          description: >-
            A map of environment names to their connection status.
          additionalProperties:
            $ref: '#/components/schemas/EnvironmentStatus'
        version:
          type: string
          description: >-
            The version of the Relay Proxy.
    EnvironmentStatus:
      type: object
      description: >-
        The connection status of a single environment.
      properties:
        status:
          type: string
          description: >-
            Whether the environment is currently connected or disconnected.
          enum:
            - connected
            - disconnected
        connectionStatus:
          type: object
          description: >-
            Detailed connection status information.
          properties:
            state:
              type: string
              description: >-
                The current connection state. VALID means connected,
                INITIALIZING means still starting up, INTERRUPTED means
                currently experiencing a problem, OFF means permanently
                failed due to an invalid SDK key.
              enum:
                - VALID
                - INITIALIZING
                - INTERRUPTED
                - OFF
            stateSince:
              type: integer
              format: int64
              description: >-
                Unix epoch timestamp when the current state began.
            lastError:
              type: object
              description: >-
                Details about the last connection error, if any.
              properties:
                kind:
                  type: string
                  description: >-
                    The type of error.
                time:
                  type: integer
                  format: int64
                  description: >-
                    Unix epoch timestamp when the error occurred.
        sdkKey:
          type: string
          description: >-
            The last four characters of the SDK key for this environment.
        envId:
          type: string
          description: >-
            The client-side environment ID.
        envKey:
          type: string
          description: >-
            The environment key.
        envName:
          type: string
          description: >-
            The environment name.
        projKey:
          type: string
          description: >-
            The project key.
        projName:
          type: string
          description: >-
            The project name.
    EvaluationContext:
      type: object
      description: >-
        A context object describing the entity for which flags
        are being evaluated.
      required:
        - kind
        - key
      properties:
        kind:
          type: string
          description: >-
            The context kind, such as "user" or a custom kind.
        key:
          type: string
          description: >-
            The unique key identifying this context.
        name:
          type: string
          description: >-
            An optional human-readable name for this context.
        anonymous:
          type: boolean
          description: >-
            Whether this context is anonymous.
      additionalProperties: true
    FlagEvaluations:
      type: object
      description: >-
        A map of flag keys to their evaluated results for a context.
      additionalProperties:
        $ref: '#/components/schemas/FlagEvaluation'
    FlagEvaluation:
      type: object
      description: >-
        The evaluated result of a single feature flag.
      properties:
        value:
          description: >-
            The evaluated value of the flag for the given context.
        variation:
          type: integer
          description: >-
            The index of the variation that was served.
        version:
          type: integer
          description: >-
            The version number of the flag.
        trackEvents:
          type: boolean
          description: >-
            Whether analytics events should be tracked for this flag.
        trackReason:
          type: boolean
          description: >-
            Whether the evaluation reason should be included in events.
        reason:
          type: object
          description: >-
            The reason for the evaluation result.
          properties:
            kind:
              type: string
              description: >-
                The kind of evaluation reason.
              enum:
                - OFF
                - FALLTHROUGH
                - TARGET_MATCH
                - RULE_MATCH
                - PREREQUISITE_FAILED
                - ERROR
    FlagData:
      type: object
      description: >-
        The complete flag data set for PHP polling mode.
      properties:
        flags:
          type: object
          description: >-
            A map of flag keys to their complete flag configurations.
          additionalProperties:
            type: object
        segments:
          type: object
          description: >-
            A map of segment keys to their complete segment configurations.
          additionalProperties:
            type: object