OneSignal Apps API

openapi: 3.0.0
info:
  contact:
    email: devrel@onesignal.com
    name: OneSignal DevRel
    url: https://onesignal.com
  description: A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com
  termsOfService: https://onesignal.com/tos
  title: OneSignal Apps API
  version: 5.5.0
servers:
- url: https://api.onesignal.com
tags:
- name: Apps
paths:
  /apps:
    get:
      description: View the details of all of your current OneSignal apps
      operationId: get_apps
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Apps'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: View apps
      tags:
      - Apps
    post:
      description: Creates a new OneSignal app
      operationId: create_app
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: Create an app
      tags:
      - Apps
  /apps/{app_id}:
    get:
      description: View the details of a single OneSignal app
      operationId: get_app
      parameters:
      - description: An app id
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: View an app
      tags:
      - Apps
    put:
      description: Updates the name or configuration settings of an existing OneSignal app
      operationId: update_app
      parameters:
      - description: An app id
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: Update an app
      tags:
      - Apps
  /apps/{app_id}/segments:
    get:
      description: Returns an array of segments from an app.
      operationId: get_segments
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: Segments are listed in ascending order of created_at date. offset will omit that number of segments from the beginning of the list. Eg offset 5, will remove the 5 earliest created Segments.
        explode: true
        in: query
        name: offset
        required: false
        schema:
          type: integer
        style: form
      - description: The amount of Segments in the response. Maximum 300.
        explode: true
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSegmentsSuccessResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Get Segments
      tags:
      - Apps
    post:
      description: 'Create a segment visible and usable in the dashboard and API - Required: OneSignal Paid Plan

        The Create Segment method is used when you want your server to programmatically create a segment instead of using the OneSignal Dashboard UI. Just like creating Segments from the dashboard you can pass in filters with multiple "AND" or "OR" operator''s.

        🚧

        Does Not Update Segments

        This endpoint will only create segments, it does not edit or update currently created Segments. You will need to use the Delete Segment endpoint and re-create it with this endpoint to edit.

        '
      operationId: create_segment
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Segment'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSegmentSuccessResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSegmentConflictResponse'
          description: Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Create Segment
      tags:
      - Apps
  /apps/{app_id}/segments/{segment_id}:
    delete:
      description: 'Delete a segment (not user devices) - Required: OneSignal Paid Plan

        You can delete a segment under your app by calling this API. You must provide an API key in the Authorization header that has admin access on the app.

        The segment_id can be found in the URL of the segment when viewing it in the dashboard.

        '
      operationId: delete_segment
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: The segment_id can be found in the URL of the segment when viewing it in the dashboard.
        explode: false
        in: path
        name: segment_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessBoolResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessBoolResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Delete Segment
      tags:
      - Apps
  /apps/{app_id}/outcomes:
    get:
      description: 'View the details of all the outcomes associated with your app


        🚧

        Requires Authentication Key

        Requires your OneSignal App''s REST API Key, available in Keys & IDs.


        🚧

        Outcome Data Limitations

        Outcomes are only accessible for around 30 days before deleted from our servers. You will need to export this data every month if you want to keep it.

        '
      operationId: get_outcomes
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: 'Required

          Comma-separated list of names and the value (sum/count) for the returned outcome data.

          Note: Clicks only support count aggregation.

          For out-of-the-box OneSignal outcomes such as click and session duration, please use the "os" prefix with two underscores. For other outcomes, please use the name specified by the user.

          Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum

          '
        explode: true
        in: query
        name: outcome_names
        required: true
        schema:
          type: string
        style: form
      - description: 'Optional

          If outcome names contain any commas, then please specify only one value at a time.

          Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count

          where "Sales, Purchase" is the custom outcomes with a comma in the name.

          '
        explode: true
        in: query
        name: outcome_names[]
        required: false
        schema:
          type: string
        style: form
      - description: 'Optional

          Time range for the returned data. The values can be 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for the last 1 month data).

          Default is 1h if the parameter is omitted.

          '
        explode: true
        in: query
        name: outcome_time_range
        required: false
        schema:
          type: string
        style: form
      - description: 'Optional

          Platform id. Refer device''s platform ids for values.

          Example:

          outcome_platform=0 for iOS

          outcome_platform=7,8 for Safari and Firefox

          Default is data from all platforms if the parameter is omitted.

          '
        explode: true
        in: query
        name: outcome_platforms
        required: false
        schema:
          type: string
        style: form
      - description: 'Optional

          Attribution type for the outcomes. The values can be direct or influenced or unattributed.

          Example: outcome_attribution=direct

          Default is total (returns direct+influenced+unattributed) if the parameter is omitted.

          '
        explode: true
        in: query
        name: outcome_attribution
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutcomesData'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: View Outcomes
      tags:
      - Apps
  /apps/{app_id}/activities/activity/{activity_type}:
    post:
      description: Remotely start a Live Activity on iOS devices via OneSignal’s REST API.
      operationId: start_live_activity
      parameters:
      - description: Your OneSignal App ID in UUID v4 format.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: The name of the Live Activity defined in your app. This should match the attributes struct used in your app's Live Activity implementation.
        explode: false
        in: path
        name: activity_type
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartLiveActivityRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartLiveActivitySuccessResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Start Live Activity
      tags:
      - Apps
  /apps/{app_id}/live_activities/{activity_id}/notifications:
    post:
      description: Updates a specified live activity.
      operationId: update_live_activity
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: Live Activity record ID
        explode: false
        in: path
        name: activity_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLiveActivityRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLiveActivitySuccessResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Update a Live Activity via Push
      tags:
      - Apps
  /apps/{app_id}/users:
    post:
      description: 'Creates a User, optionally Subscriptions owned by the User as well as Aliases.

        Aliases provided in the payload will be used to look up an existing User.'
      operationId: create_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: CREATED
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: CREATED
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: ACCEPTED
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserConflictResponse'
          description: Multiple User Identity Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
  /apps/{app_id}/users/by/{alias_label}/{alias_id}:
    delete:
      description: Removes the User identified by (:alias_label, :alias_id), and all Subscriptions and Aliases
      operationId: delete_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
    get:
      description: Returns the User’s properties, Aliases, and Subscriptions.
      operationId: get_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
    patch:
      description: Updates an existing User’s properties.
      operationId: update_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertiesBody'
          description: ACCEPTED
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
  /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity:
    get:
      description: Lists all Aliases for the User identified by (:alias_label, :alias_id).
      operationId: get_aliases
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentityBody'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
    patch:
      description: Upserts one or more Aliases to an existing User identified by (:alias_label, :alias_id).
      operationId: create_alias
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserIdentityBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentityBody'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
  /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}:
    delete:
      description: Deletes an alias by alias label
      operationId: delete_alias
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label_to_delete
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentityBody'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
  /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions:
    post:
      description: Creates a new Subscription under the User provided. Useful to add email addresses and SMS numbers to the User.
      operationId: create_subscription
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionBody'
          description: CREATED
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionBody'
          description: ACCEPTED
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Operation is not permitted due to user having the maximum number of subscriptions assigned
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
  /apps/{app_id}/subscriptions/{subscription_id}:
    delete:
      description: Deletes the Subscription.
      operationId: delete_subscription
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: subscription_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '202':
          description: ACCEPTED
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
    patch:
      description: Updates an existing Subscription’s properties.
      operationId: update_subscription
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: subscription_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionBody'
        required: true
      responses:
        '200':
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      tags:
      - Apps
  /apps/{app_id}/subscriptions/{subscription_id}/user/identity:
    get:
      description: Lists all Aliases for the User identified by :subscription_id.
      operationId: get_aliases_by_subscription
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: subscription_id
        required: true
        schema:
          type: string
        style: simple
      re

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