> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an integration

> Create an integration for a specific app.

### Supported apps

Only the following apps can be created through the API, each with its own `settings`:

| App | `app` key | Settings |
| - | - | - |
| [Email](/integrations/email) | `email` | `members` |
| [ilert](/integrations/ilert) | `ilert` | `integration_key` |
| [ntfy](/integrations/ntfy) | `ntfy` | `hostname`, `topic`, `access_token` |
| [Outgoing webhook](/integrations/outgoing-webhook) | `outgoing_webhook` | `url`, `secret` |
| [Pushover](/integrations/pushover) | `pushover` | `user_key`, `api_key` |
| [SMS](/integrations/sms) | `sms` | `members` |

<Info>The SMS integration requires a Scale plan subscription.</Info>

### Why some apps are not supported

Some integrations need a step that can't be done with an API request, so they can only be created from the <a href="https://app.phare.io/organization/apps" rel="nofollow">control panel</a>:

* **Slack** and **Discord**: You need to sign in to Slack or Discord and approve the Phare app in your browser.
* **Telegram**: The Phare bot is connected to your chat by opening a link or scanning a QR code on your device.

Requests for these apps return a `403` error. Once created in the control panel, they can still be [listed](/api-reference/platform/integrations/list-integrations), [fetched](/api-reference/platform/integrations/get-an-integration), [deleted](/api-reference/platform/integrations/delete-an-integration), and used in [alert rules](/api-reference/platform/alert-rules/create-an-alert-rule) through the API.


## OpenAPI

````yaml post /apps/{app}/integrations
openapi: 3.0.0
info:
  title: Phare
  description: >-
    Learn how to use the phare.io API. Most of the things that can be done on
    the web platform can also be achieved with the API documented on this page.
  termsOfService: https://phare.io/legal/terms-of-service
  contact:
    name: Phare
    email: support@phare.io
  version: '1.0'
servers:
  - url: https://api.phare.io
security:
  - BearerAuth: []
tags:
  - name: Users
    description: Users
  - name: Projects
    description: Projects
  - name: Alert Rules
    description: Alert Rules
  - name: Monitors
    description: Monitors
  - name: Incidents
    description: Incidents
  - name: Status Pages
    description: Status Pages
  - name: Reports
    description: Reports
  - name: Platform
    description: Platform
  - name: Integrations
    description: Integrations
  - name: Maintenance Windows
    description: Maintenance Windows
paths:
  /apps/{app}/integrations:
    post:
      tags:
        - Integrations
      summary: Create an integration
      description: Create an integration for a specific app.
      operationId: createIntegration
      parameters:
        - name: app
          in: path
          description: The app key
          required: true
          schema:
            $ref: '#/components/schemas/Platform.App.ManageableAppEnum'
        - $ref: '#/components/parameters/header_project_id'
        - $ref: '#/components/parameters/header_project_slug'
      requestBody:
        description: Integration request
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Integration name
                  type: string
                  example: DevOps Team
                  maxLength: 50
                  minLength: 2
                settings:
                  description: Settings specific to the integration app
                  anyOf:
                    - title: Empty
                      maxProperties: 0
                      type: object
                    - $ref: >-
                        #/components/schemas/Platform.App.Email.IntegrationSettings
                    - $ref: >-
                        #/components/schemas/Platform.App.Ilert.IntegrationSettings
                    - $ref: >-
                        #/components/schemas/Platform.App.Ntfy.IntegrationSettings
                    - $ref: >-
                        #/components/schemas/Platform.App.OutgoingWebhook.IntegrationSettings
                    - $ref: >-
                        #/components/schemas/Platform.App.Pushover.IntegrationSettings
                    - $ref: >-
                        #/components/schemas/Platform.App.Sms.IntegrationSettings
              required:
                - name
      responses:
        '201':
          description: Success, integration created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: Integration ID
                    type: integer
                    example: 1
                  app:
                    $ref: '#/components/schemas/Platform.App.AppEnum'
                  name:
                    description: Integration name
                    type: string
                    example: DevOps Team
                    maxLength: 50
                    minLength: 2
                  settings:
                    description: Settings specific to the integration app
                    anyOf:
                      - title: Empty
                        maxProperties: 0
                        type: object
                      - $ref: >-
                          #/components/schemas/Platform.App.Email.IntegrationSettings
                      - $ref: >-
                          #/components/schemas/Platform.App.Ilert.IntegrationSettings
                      - $ref: >-
                          #/components/schemas/Platform.App.Ntfy.IntegrationSettings
                      - $ref: >-
                          #/components/schemas/Platform.App.OutgoingWebhook.IntegrationSettings
                      - $ref: >-
                          #/components/schemas/Platform.App.Pushover.IntegrationSettings
                      - $ref: >-
                          #/components/schemas/Platform.App.Sms.IntegrationSettings
                  paused:
                    description: Integration paused status
                    type: boolean
                    example: false
                  created_at:
                    description: Date of creation for the entity
                    type: string
                    format: date-time
                  updated_at:
                    description: Date of last update for the entity
                    type: string
                    format: date-time
                required:
                  - name
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
components:
  schemas:
    Platform.App.ManageableAppEnum:
      type: string
      enum:
        - sms
        - email
        - ilert
        - ntfy
        - outgoing_webhook
        - pushover
    Platform.App.Email.IntegrationSettings:
      title: Email
      required:
        - members
      properties:
        members:
          description: IDs of the organization members receiving the alerts
          type: array
          items:
            type: integer
          example:
            - 1
            - 2
          maxItems: 100
          minItems: 1
      type: object
    Platform.App.Ilert.IntegrationSettings:
      title: ilert
      required:
        - integration_key
      properties:
        integration_key:
          description: ilert alert source integration key
          type: string
          writeOnly: true
          example: il1api00000000000000000000000000000000000000
          maxLength: 70
          minLength: 40
      type: object
    Platform.App.Ntfy.IntegrationSettings:
      title: Ntfy
      required:
        - hostname
        - topic
      properties:
        hostname:
          description: Hostname of the Ntfy server
          type: string
          example: ntfy.sh
          maxLength: 100
          minLength: 4
        topic:
          description: Ntfy topic receiving the alerts
          type: string
          example: phare-alerts
          maxLength: 255
          minLength: 1
        access_token:
          description: Ntfy access token used for authenticated topics
          type: string
          writeOnly: true
          example: tk_00000000000000000000000000000
          nullable: true
          maxLength: 32
          minLength: 32
      type: object
    Platform.App.OutgoingWebhook.IntegrationSettings:
      title: Outgoing Webhooks
      required:
        - url
        - secret
      properties:
        url:
          description: URL receiving the webhook requests
          type: string
          format: uri
          example: https://example.com/webhooks/phare
          maxLength: 250
        secret:
          description: Secret used to sign the webhook requests
          type: string
          writeOnly: true
          example: a-very-secure-secret
          maxLength: 250
          minLength: 10
      type: object
    Platform.App.Pushover.IntegrationSettings:
      title: Pushover
      required:
        - user_key
        - api_key
      properties:
        user_key:
          description: Pushover user or group key
          type: string
          writeOnly: true
          example: u00000000000000000000000000000
          maxLength: 30
          minLength: 30
        api_key:
          description: Pushover application API token
          type: string
          writeOnly: true
          example: a00000000000000000000000000000
          maxLength: 30
          minLength: 30
      type: object
    Platform.App.Sms.IntegrationSettings:
      title: SMS
      required:
        - members
      properties:
        members:
          description: IDs of the organization members receiving the alerts
          type: array
          items:
            type: integer
          example:
            - 1
            - 2
          maxItems: 100
          minItems: 1
      type: object
    Platform.App.AppEnum:
      type: string
      enum:
        - sms
        - discord
        - email
        - ilert
        - ntfy
        - outgoing_webhook
        - pushover
        - slack
        - telegram
  parameters:
    header_project_id:
      name: X-Phare-Project-Id
      in: header
      description: A project header is required when using an organization-scoped API key.
      required: false
      schema:
        type: integer
        example: 1
    header_project_slug:
      name: X-Phare-Project-Slug
      in: header
      description: A project header is required when using an organization-scoped API key.
      required: false
      schema:
        type: string
        example: luminous-guiding-tower
  responses:
    '401':
      description: Error, access unauthorized
      content:
        application/json:
          schema:
            description: Access unauthorized error schema
            properties:
              message:
                type: string
                example: Unauthorized
            type: object
    '403':
      description: Error, access forbidden
      content:
        application/json:
          schema:
            description: Access forbidden error schema
            properties:
              message:
                type: string
                example: >-
                  The platform:write permission is required to perform this
                  action.
            type: object
    '422':
      description: Error, unprocessable entity
      content:
        application/json:
          schema:
            description: Validation error schema
            properties:
              message:
                type: string
              errors:
                properties:
                  key:
                    type: array
                    items:
                      type: string
                      example: The key field is required
                type: object
            type: object
  securitySchemes:
    BearerAuth:
      type: http
      description: >-
        Use a user token to access authenticated routes. The token must be
        specified in the Authorization HTTP header with the following format
        'Authorization: Bearer <token>'.
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.