openapi: 3.0.3
info:
  title: Environments API
  description: API for managing organization environment variables and secrets
  version: 1.0.1
tags:
- name: environments
  description: Environment variables and secrets management
security:
- EpilotAuth: []
paths:
  /v1/environments:
    get:
      operationId: listEnvironmentVariables
      summary: listEnvironmentVariables
      description: List all environment variables for the organization. Returns metadata only, no secret values.
      tags:
      - environments
      responses:
        '200':
          description: List of environment variables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentVariableList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
    post:
      operationId: createEnvironmentVariable
      summary: createEnvironmentVariable
      description: Create a new environment variable or secret for the organization. If `group` is provided and the group does not yet exist, it is created automatically.
      tags:
      - environments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentVariableCreateRequest'
      responses:
        '201':
          description: Created environment variable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentVariable'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: Environment variable with this key already exists
        '500':
          description: Internal server error
  /v1/environments/groups:
    get:
      operationId: listEnvironmentGroups
      summary: listEnvironmentGroups
      description: List all environment groups for the organization.
      tags:
      - environments
      responses:
        '200':
          description: List of environment groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentGroupList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
  /v1/environments/groups/{name}:
    parameters:
    - name: name
      in: path
      required: true
      schema:
        type: string
    put:
      operationId: putEnvironmentGroup
      summary: putEnvironmentGroup
      description: Create or update an environment group by name. Acts as an upsert — creates the group if it does not exist.
      tags:
      - environments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentGroupUpsertRequest'
      responses:
        '200':
          description: Updated group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentGroup'
        '201':
          description: Created group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentGroup'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
    delete:
      operationId: deleteEnvironmentGroup
      summary: deleteEnvironmentGroup
      description: Deletes a group. Variables assigned to this group become ungrouped.
      tags:
      - environments
      responses:
        '204':
          description: Group deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Group not found
        '500':
          description: Internal server error
  /v1/environments/{key}:
    parameters:
    - name: key
      in: path
      required: true
      description: Environment variable key
      schema:
        type: string
        pattern: ^[a-z0-9][a-z0-9_.\-]{0,127}$
    get:
      operationId: getEnvironmentVariable
      summary: getEnvironmentVariable
      description: Get an environment variable by key. Returns value only for String type, omitted for SecretString.
      tags:
      - environments
      responses:
        '200':
          description: Environment variable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentVariable'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Environment variable not found
        '500':
          description: Internal server error
    put:
      operationId: updateEnvironmentVariable
      summary: updateEnvironmentVariable
      description: Create or update an environment variable. Acts as an upsert — creates the variable if it does not exist. If `group` is provided and the group does not yet exist, it is created automatically.
      tags:
      - environments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentVariableUpdateRequest'
      responses:
        '200':
          description: Updated environment variable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentVariable'
        '201':
          description: Created environment variable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentVariable'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
    delete:
      operationId: deleteEnvironmentVariable
      summary: deleteEnvironmentVariable
      description: Delete an environment variable by key.
      tags:
      - environments
      responses:
        '204':
          description: Environment variable deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Environment variable not found
        '500':
          description: Internal server error
components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    EnvironmentValueType:
      type: string
      enum:
      - String
      - SecretString
    EnvironmentVariable:
      type: object
      required:
      - key
      - type
      - created_at
      - updated_at
      properties:
        key:
          type: string
          pattern: ^[a-z0-9][a-z0-9_.\-]{0,127}$
        type:
          $ref: '#/components/schemas/EnvironmentValueType'
        description:
          type: string
        group:
          type: string
          description: Optional group name for organising variables in the UI
        value:
          type: string
          description: Value is returned for String type, omitted for SecretString
        protected:
          type: boolean
          description: Whether the variable is protected from editing
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    EnvironmentVariableListItem:
      type: object
      required:
      - key
      - type
      - created_at
      - updated_at
      properties:
        key:
          type: string
        type:
          $ref: '#/components/schemas/EnvironmentValueType'
        description:
          type: string
        group:
          type: string
          description: Optional group name for organising variables in the UI
        value:
          type: string
          description: Value is returned for String type, omitted for SecretString
        protected:
          type: boolean
          description: Whether the variable is protected from editing
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    EnvironmentVariableList:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EnvironmentVariableListItem'
    EnvironmentVariableCreateRequest:
      type: object
      required:
      - key
      - type
      properties:
        key:
          type: string
          pattern: ^[a-z0-9][a-z0-9_.\-]{0,127}$
        type:
          $ref: '#/components/schemas/EnvironmentValueType'
        description:
          type: string
        group:
          type: string
        value:
          type: string
        protected:
          type: boolean
          description: Whether the variable is protected from editing
    EnvironmentVariableUpdateRequest:
      type: object
      properties:
        type:
          description: Type of variable. Used when creating a new variable. Defaults to String.
          allOf:
          - $ref: '#/components/schemas/EnvironmentValueType'
        value:
          type: string
        description:
          type: string
        group:
          type: string
        protected:
          type: boolean
          description: Whether the variable is protected from editing
    EnvironmentGroup:
      type: object
      required:
      - name
      - created_at
      - updated_at
      properties:
        name:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    EnvironmentGroupList:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EnvironmentGroup'
    EnvironmentGroupUpsertRequest:
      type: object
      properties:
        description:
          type: string
servers:
- url: https://environments.sls.epilot.io

