openapi: 3.2.0
info:
  title: Phare Integrations API
  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: Integrations
  description: Integrations
paths:
  /apps/{app}/integrations:
    get:
      tags:
      - Integrations
      summary: List integrations
      description: Get a paginated list of integrations for a specific app.
      operationId: getIntegrations
      parameters:
      - name: app
        in: path
        description: The app key to filter integrations
        required: true
        schema:
          $ref: '#/components/schemas/Platform.App.AppEnum'
      - name: name
        in: query
        description: Filter integrations by name. Can be specified multiple times to filter by multiple names.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/header_project_id'
      - $ref: '#/components/parameters/header_project_slug'
      responses:
        '200':
          description: Success, integrations retrieved
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      properties:
                        id:
                          description: Integration ID
                          type: integer
                          example: 1
                        name:
                          description: Integration name
                          type: string
                          example: DevOps Team
                        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
                      type: object
                  meta:
                    $ref: '#/components/schemas/meta'
                  links:
                    $ref: '#/components/schemas/links'
                type: object
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /apps/{app}/integrations/{integrationId}:
    get:
      tags:
      - Integrations
      summary: Get an integration
      description: Get an integration by ID
      operationId: getIntegration
      parameters:
      - name: app
        in: path
        description: The app key
        required: true
        schema:
          type: string
      - name: integrationId
        in: path
        description: ID of the integration to show
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/header_project_id'
      - $ref: '#/components/parameters/header_project_slug'
      responses:
        '200':
          description: Success, integration retrieved
          content:
            application/json:
              schema:
                properties:
                  id:
                    description: Integration ID
                    type: integer
                    example: 1
                  name:
                    description: Integration name
                    type: string
                    example: DevOps Team
                  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
                type: object
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  parameters:
    per_page:
      name: per_page
      in: query
      description: Number of resources to return per page
      required: false
      schema:
        type: integer
        example: 20
        default: 20
        maximum: 100
        minimum: 1
    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
    page:
      name: page
      in: query
      description: Page number to show
      required: false
      schema:
        type: integer
        example: 1
        default: 1
  schemas:
    meta:
      description: Meta data for pagination
      properties:
        current_page:
          type: integer
          example: 2
        from:
          type: integer
          example: 11
        to:
          type: integer
          example: 20
        per_page:
          type: integer
          example: 100
        path:
          type: string
          example: https://api.phare.io/{resource}?page=2
      type: object
    Platform.App.AppEnum:
      type: string
      enum:
      - sms
      - discord
      - email
      - ilert
      - ntfy
      - outgoing_webhook
      - pushover
      - slack
      - telegram
    links:
      description: Links for pagination
      properties:
        first:
          type: string
          format: url
          example: https://api.phare.io/{resource}?page=2
        last:
          type:
          - string
          - 'null'
          format: url
          example: https://api.phare.io/{resource}?page=10
        prev:
          type:
          - string
          - 'null'
          format: url
          example: https://api.phare.io/{resource}?page=1
        next:
          type:
          - string
          - 'null'
          format: url
          example: https://api.phare.io/{resource}?page=1
      type: object
  responses:
    '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
    '401':
      description: Error, access unauthorized
      content:
        application/json:
          schema:
            description: Access unauthorized error schema
            properties:
              message:
                type: string
                example: Unauthorized
            type: object
    '404':
      description: Error, resource not found
      content:
        application/json:
          schema:
            description: Not found error schema
            properties:
              message:
                type: string
                example: Resource not found
            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
x-tagGroups:
- name: Phare platform
  tags:
  - Users
  - Projects
  - Alert Rules
- name: Phare uptime
  tags:
  - Monitors
  - Incidents
  - Status Pages
  - Reports
x-provenance:
  method: harvested
  publisher: Phare
  source: https://docs.phare.io/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)