Unleash Addons API

openapi: 3.2.0
info:
  title: Unleash Admin Addons API
  version: 7.4.1
  description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons).
servers:
- url: https://app.unleash-instance.example.com
  description: Your Unleash instance (replace with your actual URL)
security:
- apiKey: []
- bearerToken: []
tags:
- name: Addons
  description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons).
paths:
  /api/admin/addons:
    get:
      summary: Get All Addons and Providers
      description: Retrieve all addons and providers that are defined on this Unleash instance.
      tags:
      - Addons
      operationId: getAddons
      responses:
        '200':
          description: addonsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/addonsSchema'
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
    post:
      summary: Create a New Addon
      description: Create an addon instance. The addon must use one of the providers available on this Unleash instance.
      tags:
      - Addons
      operationId: createAddon
      requestBody:
        description: addonCreateUpdateSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addonCreateUpdateSchema'
      responses:
        '200':
          description: addonSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/addonSchema'
        '400':
          description: The request data does not match what we expect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ValidationError
                    description: The name of the error kind
                  message:
                    type: string
                    example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
                    description: A description of what went wrong.
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
        '413':
          description: The request body is larger than what we accept. By default we only accept bodies of 100kB or less
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ContentTooLarge
                    description: The name of the error kind
                  message:
                    type: string
                    example: You provided more data than we can handle. Unleash accepts at most X MB.
                    description: A description of what went wrong.
        '415':
          description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ContentTypeerror
                    description: The name of the error kind
                  message:
                    type: string
                    example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
                    description: A description of what went wrong.
  /api/admin/addons/{id}:
    get:
      summary: Get a Specific Addon
      description: Retrieve information about the addon whose ID matches the ID in the request URL.
      tags:
      - Addons
      operationId: getAddon
      responses:
        '200':
          description: addonSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/addonSchema'
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    put:
      summary: Update an Addon
      description: 'Update the addon with a specific ID. Any fields in the update object will be updated. Properties that are not included in the update object will not be affected. To empty a property, pass `null` as that property''s value.


        Note: passing `null` as a value for the description property will set it to an empty string.'
      tags:
      - Addons
      operationId: updateAddon
      requestBody:
        description: addonCreateUpdateSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addonCreateUpdateSchema'
      responses:
        '200':
          description: addonSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/addonSchema'
        '400':
          description: The request data does not match what we expect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ValidationError
                    description: The name of the error kind
                  message:
                    type: string
                    example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
                    description: A description of what went wrong.
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
        '413':
          description: The request body is larger than what we accept. By default we only accept bodies of 100kB or less
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ContentTooLarge
                    description: The name of the error kind
                  message:
                    type: string
                    example: You provided more data than we can handle. Unleash accepts at most X MB.
                    description: A description of what went wrong.
        '415':
          description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ContentTypeerror
                    description: The name of the error kind
                  message:
                    type: string
                    example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
                    description: A description of what went wrong.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    delete:
      summary: Delete an Addon
      description: Delete the addon specified by the ID in the request path.
      tags:
      - Addons
      operationId: deleteAddon
      responses:
        '200':
          description: This response has no body.
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
  /api/admin/addons/{id}/events:
    get:
      tags:
      - Addons
      operationId: getIntegrationEvents
      summary: Get Integration Events for a Specific Integration Configuration.
      description: Returns a list of integration events belonging to a specific integration configuration, identified by its id.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        schema:
          type: string
          example: '50'
        description: The number of results to return in a page. By default it is set to 50.
        in: query
      - name: offset
        schema:
          type: string
          example: '50'
        description: The number of results to skip when returning a page. By default it is set to 0.
        in: query
      responses:
        '200':
          description: '#/components/schemas/integrationEventsSchema'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/integrationEventsSchema'
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
components:
  schemas:
    addonTypeSchema:
      type: object
      additionalProperties: false
      required:
      - name
      - displayName
      - documentationUrl
      - description
      description: An addon provider. Defines a specific addon type and what the end user must configure when creating a new addon of that type.
      properties:
        name:
          type: string
          description: The name of the addon type. When creating new addons, this goes in the payload's `type` field.
          example: slack
        displayName:
          type: string
          description: The addon type's name as it should be displayed in the admin UI.
          example: Slack
        documentationUrl:
          type: string
          description: A URL to where you can find more information about using this addon type.
          example: https://docs.getunleash.io/docs/addons/slack
        description:
          type: string
          description: A description of the addon type.
          example: Allows Unleash to post updates to Slack.
        howTo:
          type: string
          description: A long description of how to use this addon type. This will be displayed on the top of configuration page. Can contain markdown.
          example: "This is **how you use** this addon type...\n  - Step 1\n  - Step 2\n  - Step 3"
        tagTypes:
          type: array
          description: A list of [Unleash tag types](https://docs.getunleash.io/concepts/feature-flags#tags) that this addon uses. These tags will be added to the Unleash instance when an addon of this type is created.
          example:
          - name: slack
            description: Slack tag used by the slack-addon to specify the slack channel.
            icon: S
          items:
            $ref: '#/components/schemas/tagTypeSchema'
        parameters:
          type: array
          description: 'The addon provider''s parameters. Use these to configure an addon of this provider type. Items with `required: true` must be provided.'
          items:
            $ref: '#/components/schemas/addonParameterSchema'
          example:
          - name: url
            displayName: Slack webhook URL
            description: (Required)
            type: url
            required: true
            sensitive: true
          - name: username
            displayName: Username
            placeholder: Unleash
            description: The username to use when posting messages to slack. Defaults to "Unleash".
            type: text
            required: false
            sensitive: false
          - name: emojiIcon
            displayName: Emoji Icon
            placeholder: ':unleash:'
            description: The emoji_icon to use when posting messages to slack. Defaults to ":unleash:".
            type: text
            required: false
            sensitive: false
          - name: defaultChannel
            displayName: Default channel
            description: (Required) Default channel to post updates to if not specified in the slack-tag
            type: text
            required: true
            sensitive: false
        events:
          type: array
          description: All the [event types](https://docs.getunleash.io/concepts/events#event-types) that are available for this addon provider.
          items:
            type: string
          example:
          - feature-created
          - feature-updated
          - feature-archived
          - feature-revived
          - feature-stale-on
          - feature-stale-off
          - feature-environment-enabled
          - feature-environment-disabled
          - feature-strategy-remove
          - feature-strategy-update
          - feature-strategy-add
          - feature-metadata-updated
          - feature-variants-updated
          - feature-project-change
        installation:
          type: object
          additionalProperties: false
          required:
          - url
          description: The installation configuration for this addon type.
          properties:
            url:
              type: string
              description: A URL to where the addon configuration should redirect to install addons of this type.
              example: https://app-for-slack.getunleash.io/install
            title:
              type: string
              description: The title of the installation configuration. This will be displayed to the user when installing addons of this type.
              example: App for Slack installation
            helpText:
              type: string
              description: The help text of the installation configuration. This will be displayed to the user when installing addons of this type.
              example: Clicking the Install button will send you to Slack to initiate the installation procedure for the Unleash App for Slack for your workspace
        alerts:
          type: array
          description: A list of alerts to display to the user when installing addons of this type.
          items:
            type: object
            additionalProperties: false
            required:
            - type
            - text
            properties:
              type:
                type: string
                enum:
                - success
                - info
                - warning
                - error
                description: The type of alert. This determines the color of the alert.
                example: info
              text:
                type: string
                description: The text of the alert. This is what will be displayed to the user.
                example: Please ensure you have the Unleash App for Slack installed in your Slack workspace if you haven't installed it already. If you want the Unleash App for Slack bot to post messages to private channels, you'll need to invite it to those channels.
        deprecated:
          type: string
          description: This should be used to inform the user that this addon type is deprecated and should not be used. Deprecated addons will show a badge with this information on the UI.
          example: This integration is deprecated. Please try the new integration instead.
    addonCreateUpdateSchema:
      type: object
      required:
      - provider
      - enabled
      - parameters
      - events
      description: Data required to create or update an [Unleash addon](https://docs.getunleash.io/integrate) instance.
      properties:
        provider:
          type: string
          description: 'The addon provider, such as "webhook" or "slack". This string is **case sensitive** and maps to the provider''s `name` property.


            The list of all supported providers and their parameters for a specific Unleash instance can be found by making a GET request to the `api/admin/addons` endpoint: the `providers` property of that response will contain all available providers.


            The default set of providers can be found in the [addons reference documentation](https://docs.getunleash.io/integrate). The default supported options are:

            - `datadog` for [Datadog](https://docs.getunleash.io/integrate/datadog)

            - `slack` for [Slack](https://docs.getunleash.io/integrate/slack)

            - `teams` for [Microsoft Teams](https://docs.getunleash.io/integrate/teams)

            - `webhook` for [webhooks](https://docs.getunleash.io/integrate/webhook)


            The provider you choose for your addon dictates what properties the `parameters` object needs. Refer to the documentation for each provider for more information.

            '
          example: webhook
        description:
          type: string
          description: A description of the addon.
          example: This addon posts updates to our internal feature tracking system whenever a feature is created or updated.
        enabled:
          type: boolean
          description: Whether the addon should be enabled or not.
        parameters:
          type: object
          additionalProperties: {}
          example:
            url: http://localhost:4242/webhook
          description: Parameters for the addon provider. This object has different required and optional properties depending on the provider you choose. Consult the documentation for details.
        events:
          type: array
          description: The event types that will trigger this specific addon.
          items:
            type: string
          example:
          - feature-created
          - feature-updated
        projects:
          type: array
          description: The projects that this addon will listen to events from. An empty list means it will listen to events from **all** projects.
          example:
          - new-landing-project
          - signups-v2
          items:
            type: string
        environments:
          type: array
          description: The list of environments that this addon will listen to events from. An empty list means it will listen to events from **all** environments.
          example:
          - development
          - production
          items:
            type: string
    integrationEventSchema:
      type: object
      required:
      - id
      - integrationId
      - createdAt
      - state
      - stateDetails
      - event
      - details
      description: An object describing an integration event.
      additionalProperties: false
      properties:
        id:
          type: string
          pattern: ^[0-9]+$
          description: The integration event's ID. Integration event IDs are incrementing integers. In other words, a more recently created integration event will always have a higher ID than an older one. This ID is represented as a string since it is a BigInt.
          example: '7'
        integrationId:
          type: integer
          description: The ID of the integration that the integration event belongs to.
          example: 42
        createdAt:
          type: string
          format: date-time
          description: The date and time of when the integration event was created. In other words, the date and time of when the integration handled the event.
          example: '2023-12-27T13:37:00+01:00'
        state:
          type: string
          enum:
          - success
          - failed
          - successWithErrors
          description: The state of the integration event. Can be one of `success`, `failed` or `successWithErrors`.
          example: failed
        stateDetails:
          type: string
          description: Details about the state of the integration event.
          example: 'Status code: 429 - Rate limit reached.'
        event:
          $ref: '#/components/schemas/eventSchema'
          description: The event that triggered this integration event.
        details:
          type: object
          x-enforcer-exception-skip-codes: WSCH006
          description: Detailed information about the integration event. The contents vary depending on the type of integration and the specific details.
          example:
            message: '*user@yourcompany.com* created a new *slack-app* integration configuration'
            channels:
            - engineering
         

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unleash/refs/heads/main/openapi/unleash-addons-api-openapi.yml