openapi: 3.1.0
info:
  title: Sentry Integrations API
  description: >-
    The Integrations API provides endpoints for managing third-party
    integrations within Sentry organizations, including creating and managing
    data forwarders, handling external user and team records, and controlling
    integration configurations.
  version: 0.0.1
  contact:
    name: Sentry Support
    url: https://sentry.io/support/
    email: support@sentry.io
servers:
  - url: https://sentry.io/api/0
    description: Sentry Production API
security:
  - BearerAuth: []
tags:
  - name: Data Forwarders
    description: Manage data forwarding configurations
  - name: External Teams
    description: Manage external team mappings
  - name: External Users
    description: Manage external user mappings
  - name: Integrations
    description: Manage third-party integrations
paths:
  /organizations/{organization_id_or_slug}/integrations/:
    get:
      operationId: listOrganizationIntegrations
      summary: Sentry List an organization's available integrations
      description: Returns a list of integrations configured for an organization.
      tags:
        - Integrations
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - name: providerKey
          in: query
          description: Filter by integration provider key.
          schema:
            type: string
      responses:
        '200':
          description: A list of integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Integration'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
  /organizations/{organization_id_or_slug}/integrations/{integration_id}/:
    get:
      operationId: retrieveOrganizationIntegration
      summary: Sentry Retrieve an integration for an organization
      description: Returns details for a specific integration.
      tags:
        - Integrations
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - $ref: '#/components/parameters/IntegrationId'
      responses:
        '200':
          description: Integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
        '401':
          description: Unauthorized.
        '404':
          description: Integration not found.
    delete:
      operationId: deleteOrganizationIntegration
      summary: Sentry Delete an integration for an organization
      description: Removes an integration from the organization.
      tags:
        - Integrations
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - $ref: '#/components/parameters/IntegrationId'
      responses:
        '204':
          description: Integration deleted.
        '401':
          description: Unauthorized.
        '404':
          description: Integration not found.
  /organizations/{organization_id_or_slug}/config/integrations/:
    get:
      operationId: getIntegrationProviderInfo
      summary: Sentry Get integration provider information
      description: Returns available integration providers and their configurations.
      tags:
        - Integrations
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
      responses:
        '200':
          description: Integration provider information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        name:
                          type: string
                        canAdd:
                          type: boolean
                        features:
                          type: array
                          items:
                            type: string
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
  /organizations/{organization_id_or_slug}/data-forwarders/:
    get:
      operationId: listDataForwarders
      summary: Sentry Retrieve data forwarders for an organization
      description: Returns a list of data forwarders configured for the organization.
      tags:
        - Data Forwarders
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
      responses:
        '200':
          description: A list of data forwarders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataForwarder'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
    post:
      operationId: createDataForwarder
      summary: Sentry Create a data forwarder for an organization
      description: Creates a new data forwarder for the organization.
      tags:
        - Data Forwarders
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: The name of the data forwarder.
      responses:
        '201':
          description: Data forwarder created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataForwarder'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
  /organizations/{organization_id_or_slug}/data-forwarders/{forwarder_id}/:
    put:
      operationId: updateDataForwarder
      summary: Sentry Update a data forwarder for an organization
      description: Updates an existing data forwarder.
      tags:
        - Data Forwarders
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - name: forwarder_id
          in: path
          required: true
          description: The ID of the data forwarder.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: Data forwarder updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataForwarder'
        '401':
          description: Unauthorized.
        '404':
          description: Not found.
    delete:
      operationId: deleteDataForwarder
      summary: Sentry Delete a data forwarder for an organization
      description: Deletes a data forwarder.
      tags:
        - Data Forwarders
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - name: forwarder_id
          in: path
          required: true
          description: The ID of the data forwarder.
          schema:
            type: string
      responses:
        '204':
          description: Data forwarder deleted.
        '401':
          description: Unauthorized.
        '404':
          description: Not found.
  /organizations/{organization_id_or_slug}/external-users/:
    post:
      operationId: createExternalUser
      summary: Sentry Create an external user
      description: Creates a mapping between a Sentry user and an external service user.
      tags:
        - External Users
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - externalName
                - provider
                - memberId
              properties:
                externalName:
                  type: string
                  description: The external service username.
                provider:
                  type: string
                  description: The integration provider (e.g., github, gitlab).
                memberId:
                  type: integer
                  description: The Sentry member ID.
                integrationId:
                  type: integer
                  description: The integration ID.
      responses:
        '201':
          description: External user created.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
  /organizations/{organization_id_or_slug}/external-users/{external_user_id}/:
    put:
      operationId: updateExternalUser
      summary: Sentry Update an external user
      description: Updates an external user mapping.
      tags:
        - External Users
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - name: external_user_id
          in: path
          required: true
          description: The ID of the external user.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                externalName:
                  type: string
                provider:
                  type: string
      responses:
        '200':
          description: External user updated.
        '401':
          description: Unauthorized.
        '404':
          description: Not found.
    delete:
      operationId: deleteExternalUser
      summary: Sentry Delete an external user
      description: Deletes an external user mapping.
      tags:
        - External Users
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - name: external_user_id
          in: path
          required: true
          description: The ID of the external user.
          schema:
            type: string
      responses:
        '204':
          description: External user deleted.
        '401':
          description: Unauthorized.
        '404':
          description: Not found.
  /organizations/{organization_id_or_slug}/external-teams/:
    post:
      operationId: createExternalTeam
      summary: Sentry Create an external team
      description: Creates a mapping between a Sentry team and an external service team.
      tags:
        - External Teams
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - externalName
                - provider
                - teamId
              properties:
                externalName:
                  type: string
                  description: The external service team name.
                provider:
                  type: string
                  description: The integration provider.
                teamId:
                  type: integer
                  description: The Sentry team ID.
                integrationId:
                  type: integer
                  description: The integration ID.
      responses:
        '201':
          description: External team created.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
  /organizations/{organization_id_or_slug}/external-teams/{external_team_id}/:
    put:
      operationId: updateExternalTeam
      summary: Sentry Update an external team
      description: Updates an external team mapping.
      tags:
        - External Teams
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - name: external_team_id
          in: path
          required: true
          description: The ID of the external team.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                externalName:
                  type: string
                provider:
                  type: string
      responses:
        '200':
          description: External team updated.
        '401':
          description: Unauthorized.
        '404':
          description: Not found.
    delete:
      operationId: deleteExternalTeam
      summary: Sentry Delete an external team
      description: Deletes an external team mapping.
      tags:
        - External Teams
      parameters:
        - $ref: '#/components/parameters/OrganizationIdOrSlug'
        - name: external_team_id
          in: path
          required: true
          description: The ID of the external team.
          schema:
            type: string
      responses:
        '204':
          description: External team deleted.
        '401':
          description: Unauthorized.
        '404':
          description: Not found.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authentication token for the Sentry API.
  parameters:
    OrganizationIdOrSlug:
      name: organization_id_or_slug
      in: path
      required: true
      description: The ID or slug of the organization.
      schema:
        type: string
    IntegrationId:
      name: integration_id
      in: path
      required: true
      description: The ID of the integration.
      schema:
        type: string
  schemas:
    Integration:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        icon:
          type: string
          nullable: true
        domainName:
          type: string
        provider:
          type: object
          properties:
            key:
              type: string
            name:
              type: string
        status:
          type: string
        configData:
          type: object
          nullable: true
        dateCreated:
          type: string
          format: date-time
      required:
        - id
        - name
        - provider
    DataForwarder:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        dateCreated:
          type: string
          format: date-time
      required:
        - id
        - name