Knock Variables API

openapi: 3.2.0
info:
  title: Knock Management API (mAPI) Variables API
  version: '1.0'
  description: Knock Management API (mAPI) — the resource-management surface for Knock. Programmatic CRUD over Workflows, Channels, Email Layouts, Partials, Templates, Translations, Audiences, Broadcasts, Guides, Message Types, Variables, Members, Channel Groups, Environments, Branches, Commits, and API Keys. Distinct from the runtime Knock API (api.knock.app) — mAPI lives at control.knock.app and is what powers the Knock CLI and MCP server.
  contact:
    name: Knock
    url: https://knock.app
servers:
- url: https://control.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- name: Variables
paths:
  /v1/variables/{key}:
    get:
      callbacks: {}
      description: Returns a single variable by key with per-environment value overrides.
      operationId: getVariable
      parameters:
      - description: The key of the variable to retrieve.
        in: path
        name: key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variable'
          description: OK
      summary: Get a variable
      tags:
      - Variables
  /v1/variables:
    get:
      callbacks: {}
      description: Returns a list of variables. When an environment is specified, returns per-environment variables. Otherwise, returns project-scoped variables with per-environment overrides.
      operationId: listVariables
      parameters:
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      - description: Filter variables by type. Supports 'public' or 'secret'.
        in: query
        name: type
        required: false
        schema:
          enum:
          - public
          - secret
          type: string
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries after.
        in: query
        name: after
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries before.
        in: query
        name: before
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The number of entries to fetch per-page.
        in: query
        name: limit
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A paginated list of Variable. Contains a list of entries and page information.
                example:
                  entries:
                  - description: This is a description of my variable.
                    environment_values:
                      development: dev_value
                      production: prod_value
                    inserted_at: '2021-01-01T00:00:00Z'
                    key: my_variable
                    type: public
                    updated_at: '2021-01-01T00:00:00Z'
                    value: my_value
                  page_info:
                    after: null
                    before: null
                    page_size: 25
                properties:
                  entries:
                    description: A list of entries.
                    items:
                      $ref: '#/components/schemas/Variable'
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo'
                required:
                - entries
                - page_info
                title: PaginatedVariableResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List variables
      tags:
      - Variables
components:
  schemas:
    PageInfo:
      description: The information about a paginated result.
      example:
        after: null
        before: null
        page_size: 25
      properties:
        after:
          description: The cursor to fetch entries after. Will only be present if there are more entries to fetch.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        before:
          description: The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        page_size:
          description: The number of entries to fetch per-page.
          type: integer
          x-struct: null
          x-validate: null
      required:
      - page_size
      title: PageInfo
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.PageInfo
      x-validate: null
    Variable:
      description: An environment variable object.
      example:
        description: This is a description of my variable.
        environment_values:
          development: dev_value
          production: prod_value
        inserted_at: '2021-01-01T00:00:00Z'
        key: my_variable
        type: public
        updated_at: '2021-01-01T00:00:00Z'
        value: my_value
      properties:
        description:
          description: The description of the variable.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        environment_values:
          additionalProperties:
            type:
            - string
            - 'null'
            x-struct: null
            x-validate: null
          description: A map of environment slugs to their override values. Only present for project-scoped responses.
          type: object
          x-struct: null
          x-validate: null
        inserted_at:
          description: The timestamp of when the variable was created.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        key:
          description: The key of the variable.
          type: string
          x-struct: null
          x-validate: null
        type:
          default: public
          description: The type of the variable.
          enum:
          - public
          - secret
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: The timestamp of when the variable was last updated.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        value:
          description: The default value of the variable. For secret variables, this is obfuscated.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
      required:
      - key
      - type
      - inserted_at
      - updated_at
      title: Variable
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.Variable
      x-validate: null
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Knock service token (kst_...) as a Bearer token.