MagicBell user API

openapi: 3.0.3
info:
  title: MagicBell apns user API
  description: OpenAPI 3.0.3 Specification for MagicBell API.
  contact:
    name: MagicBell
    url: https://magicbell.com
    email: hello@magicbell.com
  version: 2.0.0
servers:
- url: https://api.magicbell.com/v2
  description: MagicBell REST API Base URL
tags:
- name: user
paths:
  /channels/mobile_push/apns/tokens:
    get:
      tags:
      - user
      description: Lists all mobile_push tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
      operationId: get_mobile_push_apns_tokens
      parameters:
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
      - name: page[after]
        in: query
        required: false
        schema:
          type: string
      - name: page[before]
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfAPNSTokenResponses'
    post:
      tags:
      - user
      description: Saves a mobile_push token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
      operationId: save_mobile_push_apns_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APNSToken'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APNSToken'
  /channels/mobile_push/apns/tokens/{token_id}:
    delete:
      tags:
      - user
      description: Revokes one of the authenticated user's mobile_push tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
      operationId: discard_mobile_push_apns_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscardResult'
    get:
      tags:
      - user
      description: Retrieves details of a specific mobile_push token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
      operationId: get_mobile_push_apns_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APNSTokenResponse'
  /channels/mobile_push/expo/tokens:
    get:
      tags:
      - user
      description: Lists all mobile_push tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
      operationId: get_mobile_push_expo_tokens
      parameters:
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
      - name: page[after]
        in: query
        required: false
        schema:
          type: string
      - name: page[before]
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfExpoTokenResponses'
    post:
      tags:
      - user
      description: Saves a mobile_push token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
      operationId: save_mobile_push_expo_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpoToken'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpoToken'
  /channels/mobile_push/expo/tokens/{token_id}:
    delete:
      tags:
      - user
      description: Revokes one of the authenticated user's mobile_push tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
      operationId: discard_mobile_push_expo_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscardResult'
    get:
      tags:
      - user
      description: Retrieves details of a specific mobile_push token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
      operationId: get_mobile_push_expo_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpoTokenResponse'
  /channels/mobile_push/fcm/tokens:
    get:
      tags:
      - user
      description: Lists all mobile_push tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
      operationId: get_mobile_push_fcm_tokens
      parameters:
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
      - name: page[after]
        in: query
        required: false
        schema:
          type: string
      - name: page[before]
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfFCMTokenResponses'
    post:
      tags:
      - user
      description: Saves a mobile_push token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
      operationId: save_mobile_push_fcm_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FCMToken'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FCMToken'
  /channels/mobile_push/fcm/tokens/{token_id}:
    delete:
      tags:
      - user
      description: Revokes one of the authenticated user's mobile_push tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
      operationId: discard_mobile_push_fcm_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscardResult'
    get:
      tags:
      - user
      description: Retrieves details of a specific mobile_push token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
      operationId: get_mobile_push_fcm_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FCMTokenResponse'
  /channels/slack/tokens:
    get:
      tags:
      - user
      description: Lists all slack tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
      operationId: get_slack_tokens
      parameters:
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
      - name: page[after]
        in: query
        required: false
        schema:
          type: string
      - name: page[before]
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfSlackTokenResponses'
    post:
      tags:
      - user
      description: Saves a slack token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
      operationId: save_slack_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackToken'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackToken'
      x-forbid-unknown-cookie: true
      x-forbid-unknown-header: true
      x-forbid-unknown-path: true
      x-forbid-unknown-query: true
  /channels/slack/tokens/{token_id}:
    delete:
      tags:
      - user
      description: Revokes one of the authenticated user's slack tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
      operationId: discard_slack_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscardResult'
    get:
      tags:
      - user
      description: Retrieves details of a specific slack token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
      operationId: get_slack_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackTokenResponse'
  /channels/teams/tokens:
    get:
      tags:
      - user
      description: Lists all teams tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
      operationId: get_teams_tokens
      parameters:
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
      - name: page[after]
        in: query
        required: false
        schema:
          type: string
      - name: page[before]
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfTeamsTokenResponses'
    post:
      tags:
      - user
      description: Saves a teams token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
      operationId: save_teams_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamsToken'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsToken'
  /channels/teams/tokens/{token_id}:
    delete:
      tags:
      - user
      description: Revokes one of the authenticated user's teams tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
      operationId: discard_teams_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscardResult'
    get:
      tags:
      - user
      description: Retrieves details of a specific teams token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
      operationId: get_teams_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsTokenResponse'
  /channels/web_push/tokens:
    get:
      tags:
      - user
      description: Lists all web_push tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
      operationId: get_web_push_tokens
      parameters:
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
      - name: page[after]
        in: query
        required: false
        schema:
          type: string
      - name: page[before]
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfWebPushTokenResponses'
    post:
      tags:
      - user
      description: Saves a web_push token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
      operationId: save_web_push_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebPushToken'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebPushToken'
  /channels/web_push/tokens/{token_id}:
    delete:
      tags:
      - user
      description: Revokes one of the authenticated user's web_push tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
      operationId: discard_web_push_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscardResult'
    get:
      tags:
      - user
      description: Retrieves details of a specific web_push token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
      operationId: get_web_push_token
      parameters:
      - name: token_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebPushTokenResponse'
  /integrations/inbox/installations:
    post:
      tags:
      - user
      description: Creates a new installation of a inbox integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.
      operationId: save_inbox_installation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxConfig'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxConfig'
  /integrations/inbox/installations/start:
    post:
      tags:
      - user
      description: Initiates the installation flow for a inbox integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.
      operationId: start_inbox_installation
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxConfig'
  /integrations/slack/installations:
    post:
      tags:
      - user
      description: Creates a new installation of a slack integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.
      operationId: save_slack_installation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackInstallation'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackInstallation'
  /integrations/slack/installations/finish:
    post:
      tags:
      - user
      description: Completes the installation flow for a slack integration. This endpoint is typically called after the user has completed any required authorization steps with slack.
      operationId: finish_slack_installation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackFinishInstallResponse'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackInstallation'
  /integrations/slack/installations/start:
    post:
      tags:
      - user
      description: Initiates the installation flow for a slack integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.
      operationId: start_slack_installation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackStartInstall'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackStartInstallResponseContent'
      x-forbid-unknown-cookie: true
      x-forbid-unknown-header: true
      x-forbid-unknown-path: true
      x-forbid-unknown-query: true
  /integrations/templates/installations:
    post:
      tags:
      - user
      description: Creates a new installation of a templates integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.
      operationId: save_templates_installation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplatesInstallation'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesInstallation'
  /integrations/web_push/installations:
    post:
      tags:
      - user
      description: Creates a new installation of a web_push integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.
      operationId: save_web_push_installation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebPushToken'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebPushToken'
  /integrations/web_push/installations/start:
    post:
      tags:
      - user
      description: Initiates the installation flow for a web_push integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.
      operationId: start_web_push_installation
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebPushStartInstallationResponse'
components:
  schemas:
    InboxConfig:
      required:
      - theme
      - locale
      - images
      type: object
      properties:
        images:
          minProperties: 1
          required:
          - emptyInboxUrl
          type: object
          properties:
            emptyInboxUrl:
              type: string
          nullable: true
        locale:
          minLength: 2
          type: string
          nullable: true
        theme:
          minProperties: 1
          type: object
          properties:
            banner:
              required:
              - fontSize
              - backgroundColor
              - textColor
              type: object
              properties:
                backgroundColor:
                  type: string
                backgroundOpacity:
                  type: number
                fontSize:
                  type: string
                textColor:
                  type: string
            dialog:
              required:
              - backgroundColor
              - textColor
              - accentColor
              type: object
              properties:
                accentColor:
                  type: string
                backgroundColor:
                  type: string
                textColor:
                  type: string
            footer:
              required:
              - fontSize
              - backgroundColor
              - textColor
              - borderRadius
              type: object
              properties:
                backgroundColor:
                  type: string
                borderRadius:
                  type: string
                fontSize:
                  type: string
                textColor:
                  type: string
            header:
              required:
              - fontFamily
              - fontSize
              - backgroundColor
              - textColor
              - borderRadius
              type: object
              properties:
                backgroundColor:
                  type: string
                borderRadius:
                  type: string
                fontFamily:
                  type: string
                fontSize:
                  type: string
                textColor:
                  type: string
            icon:
              required:
              - borderColor
              - width
              type: object
              properties:
                borderColor:
                  type: string
                width:
                  type: string
            notification:
              required:
              - default
              - unseen
              - unread
              type: object
              properties:
                default:
                  required:
                  - fontFamily
                  - fontSize
                  - textColor
                  - borderRadius
                  - backgroundColor
                  - margin
                  type: object
                  properties:
                    backgroundColor:
                      type: string
                    borderRadius:
                      type: string
                    fontFamily:
                      type: string
                    fontSize:
                      type: string
                    hover:
                      required:
                      - backgroundColor
                      type: object
                      properties:
                        backgroundColor:
                          type: string
                    margin:
                      type: string
                    state:
                      required:
                      - color
                      type: object
                      properties:
                        color:
                          type: string
                    textColor:
                      type: string
                unread:
                  required:
                  - textColor
                  - backgroundColor
                  type: object
                  properties:
                    backgroundColor:
                      type: string
                    hover:
                      required:
                      - backgroundColor
                      type: object
                      properties:
                        backgroundColor:
                          type: string
                    state:
                      required:
                      - color
                      type: object
                      properties:
                        color:
                          type: string
                    textColor:
                      type: string
                unseen:
                  required:
                  - textColor
                  - backgroundColor
                  type: object
                  properties:
                    backgroundColor:
                      type: string
                    hover:
                      required:
                      - backgroundColor
                      type: object
                      properties:
                        backgroundColor:
                          type: string
                    state:
                      required:
                      - color
                      type: object
                      properties:
                        color:
                          type: string
                    textColor:
                      type: string
            unseenBadge:
              required:
              - backgroundColor
              type: object
              properties:
                backgroundColor:
                  type: string
          nullable: true
      example:
        images:
          emptyInboxUrl: ''
        locale: de
        theme:
          banner:
            backgroundColor: '#F8F5FF'
            fontSize: 14px
            textColor: '#3A424D'
          dialog:
            accentColor: '#5225C1'
            backgroundColor: '#F5F5F5'
            textColor: '#313131'
          footer:
            backgroundColor: '#FFFFFF'
            borderRadius: 16px
            fontFamily: inherit
            fontSize: 15px
            textColor: '#5225C1'
          header:
            backgroundColor: '#FFFFFF'
            borderRadius: 16px
            fontFamily: inherit
            fontSize: 15px
            textColor: '#5225C1'
          icon:
            borderColor: '#EDEDEF'
            width: 24px
          unseenBadge:
            backgroundColor: '#F80808'
    SlackStartInstallResponseContent:
      type: object
      properties:
        app_id:
          type: string
        auth_url:
          type: string
        scopes:
          type: array
          items:
            type: string
      example:
        app_id: app-id
        auth_url: https://slack.com/oauth/v2/authorize?client_id=app-id&scope=channels:read,chat:write
        scopes:
        - channels:read
        - chat:write
    TemplatesInstallation:
      required:
      - text
      - channel
      type: object
      properties:
        category:
          type: string
          nullable: true
        channel:
          type: string
        text:
          type: string
      example:
        channel: email
        text: Installation
    SlackToken:
      minProperties: 1
      type: object
      properties:
        oauth:
          required:
          - channel_id
          - installation_id
          type: object
          properties:
            channel_id:
              type: string
            installation_id:
              type: string
            scope:
              type: string
        webhook:
          required:
          - url
          type: object
          properties:
            url:
              minLength: 1
              type: string
              format: uri
      additionalProperties: false
      example:
        webhook:
          url: https://example.com/webhook
    ArrayOfTeamsTokenResponses:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TeamsTokenResponse'
        links:
          $ref: '#/components/schemas/Links'
      example:
        data:
        - created_at: '2021-01-01T00:00:00Z'
          discarded_at: '2021-01-01T00:00:00Z'
          id: '123'
          updated_at: '2021-01-01T00:00:00Z'
        links:
          first: https://api.magicbell.com/v1/example
          next: https://api.magicbell.com/v1/example?page[next]=abc
          prev: null
    ExpoTokenResponse:
      required:
      - created_at
      - device_token
      - id
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        device_token:
          minLength: 1
          type: string
        discarded_at:
          type: string
          format: date-time
          nullable: true
        id:
          type: string
        updated_at:
          type: string
          format: date-time
          nullable: true
      example:
        created_at: '2021-01-01T00:00:00Z'
        device_token: expo-device-id
        discarded_at: '2021-01-01T00:00:00Z'
        id: '123'
        updated_at: '2021-01-01T00:00:00Z'
    SlackFinishInstallResponse:
      required:
      - app_id
      - code
      type: object
      properties:
        app_id:
          type: string
        code:
          type: string
        redirect_url:
          type: string
      example:
        app_id: '12345678901'
        code: string
        redirect_url: string
    FCMTokenResponse:
      required:
      - created_at
      - device_token
      - id
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        device_token:
          minLength: 64
          type: string
        discarded_at:
          type: string
          format: date-time
          nullable: true
        id:
          type: string
        installation_id:
          enum:
          - development
          - production
          type: string
        updated_at:
          type: string
          format: date-time
          nullable: true
      example:
        created_at

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