openapi: 3.0.3
info:
  title: Push API
  description: |
    APIs to send push notification to all devices connected to your account or or a team.

    The targeting is based on which API key you specify in the request: 
    If you use you account API key the notification will be send to all devices in your account. 
    If you specify a team API key then the notification will be send to all devices for every member in the team.
  termsOfService: https://push.techulus.com/terms
  contact:
    email: support@techulus.com
  version: 1.0.11
externalDocs:
  description: Find out more about Push
  url: https://push.techulus.com

servers:
  - url: https://push.techulus.com/api/v1

tags:
  - name: notify
    description: Notification Endpoints

paths:
  /notify:
    post:
      tags:
        - notify
      summary: Sync Request
      operationId: notify
      requestBody:
        description: Notification
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Notification"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Server Error
      security:
        - api_key_header: []
  /notify-async:
    post:
      tags:
        - notify
      summary: Async Request, recommened for teams
      operationId: notifyAsync
      requestBody:
        description: Notification
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Notification"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AsyncSuccessResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Server Error
      security:
        - api_key_header: []
  /notify/{apiKey}:
    post:
      tags:
        - notify
      operationId: notifyWithKey
      parameters:
        - in: path
          name: apiKey
          schema:
            type: string
          required: true
          description: Account / Team API Key
      requestBody:
        description: Notification
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Notification"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Server Error
    get:
      tags:
        - notify
      summary: Suitable for webhooks
      operationId: notifyWebhook
      parameters:
        - in: path
          name: apiKey
          schema:
            type: string
          required: true
          description: Account / Team API Key
        - in: query
          name: title
          schema:
            type: string
          required: true
          description: Notification title
        - in: query
          name: body
          schema:
            type: string
          required: true
          description: Notification Body
        - in: query
          name: sound
          schema:
            type: string
          description: Notification sound, valid options are default, arcade, correct, fail, harp, reveal, bubble, doorbell, flute, money, scifi, clear, elevator, guitar, pop.
        - in: query
          name: channel
          schema:
            type: string
          description: Notification channel, alphanumerical string and hyphens only.
        - in: query
          name: link
          schema:
              type: string
          description: Notification link URL (URL Encoded)
        - in: query
          name: image
          schema:
              type: string
          description: Notification image URL (URL Encoded)
        - in: query
          name: timeSensitive
          schema:
            type: boolean
          description: Time sensitive notifications will be delivered immediately, even if the device is in do not disturb mode. (iOS only)
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Server Error
  /notify/group/{groupId}:
    post:
      tags:
        - notify
      summary: Send notification to a device group
      operationId: notifyGroup
      parameters:
        - in: path
          name: groupId
          schema:
            type: string
          required: true
          description: Device Group ID
      requestBody:
        description: Notification
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Notification"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Server Error
      security:
        - api_key_header: []
components:
  schemas:
    Notification:
      required:
        - title
        - body
      type: object
      properties:
        title:
          type: string
          description: Notification title
        body:
          type: string
          description: Notification Body
        sound:
          type: string
          description: Notification sound, valid options are default, arcade, correct, fail, harp, reveal, bubble, doorbell, flute, money, scifi, clear, elevator, guitar, pop.
        channel:
          type: string
          description: Notification channel, alphanumerical string and hyphens only.
          default: feed
        link:
          type: string
          description: Notification link (URL)
        image:
          type: string
          description: Notification image (URL)
        timeSensitive:
          description: Time sensitive notifications will be delivered immediately, even if the device is in do not disturb mode. (iOS only)
          type: boolean
          default: false
    SuccessResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
        message:
          type: string
        responses:
          type: array
          items:
            type: object
            required:
              - success
              - message
            properties:
              success:
                type: boolean
              message:
                type: string
    AsyncSuccessResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
        message:
          type: string
        error:
          type: object

  securitySchemes:
    api_key_header:
      type: apiKey
      name: x-api-key
      description: Account / Team API Key
      in: header