openapi: 3.0.0
externalDocs:
  description: Pushcut Help Page
  url: https://www.pushcut.io/help
info:
  contact:
    name: Pushcut
    email: feedback@pushcut.io
    url: https://www.pushcut.io
  description: API to send Pushcut notifications, execute Automation Server actions, and register custom webhooks as online actions.
  title: Pushcut API
  version: v1
  x-logo:
    url: https://www.pushcut.io/assets/pushcut-icon.png
    altText: Pushcut Logo
paths:
  /devices:
    get:
      operationId: GetDevices
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                items:
                  properties:
                    id:
                      description: Name of the device
                      type: string
                      example: Simon's iPhone
                  type: object
                type: array
        "401":
          $ref: "definitions.yaml#/components/responses/401"
      summary: Get devices
      description: Gets a list of all active devices.
      tags:
        - Notifications
      x-ms-visibility: internal
  /notifications:
    get:
      operationId: GetNotifications
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                items:
                  properties:
                    id:
                      description: Name of the notification definition
                      type: string
                      example: MyNotification
                    title:
                      type: string
                      description: Title of the notification
                      example: Notification Title
                  type: object
                type: array
        "401":
          $ref: "definitions.yaml#/components/responses/401"
      summary: Get defined notifications
      description: Gets a list of all defined notifications.
      tags:
        - Notifications
      x-ms-visibility: internal
  "/notifications/{notificationName}":
    post:
      description: Sends a smart notification to your devices.
      operationId: SendNotification
      summary: Send a smart notification
      tags:
        - Notifications
      x-ms-visibility: important
      parameters:
        - description: Notification Name
          x-ms-summary: Notification
          in: path
          name: notificationName
          required: true
          example: MyNotification
          x-ms-dynamic-values:
            operationId: GetNotifications
            value-path: id
            value-title: id
          x-ms-visibility: important
          schema:
            type: string
      requestBody:
        description: Extend and customize the defined notification by providing dynamic content.
        content:
          application/json:
            schema:
              $ref: "components/schemas/notifications.yaml#/Notification"
      responses:
        "200": { $ref: "#/components/responses/NotificationSent"}
        "202": { $ref: "#/components/responses/NotificationScheduled"}
        "400": { $ref: "definitions.yaml#/components/responses/400" }
        "401": { $ref: "definitions.yaml#/components/responses/401" }
        "404": { $ref: "definitions.yaml#/components/responses/404" }
  "/submittedNotifications/{notificationId}":
    delete:
      description: Attempts to remove/cancel a previously-submitted notification.
      operationId: CancelNotification
      summary: Cancel a sent notification
      tags:
        - Notifications
      x-ms-visibility: important
      parameters:
        - description: Notification ID
          x-ms-summary: Notification
          in: path
          name: notificationId
          required: true
          example: MyNotificationId
          x-ms-visibility: important
          schema:
            type: string
        - in: query
          name: devices
          description: > 
            Device(s) for which to cancel notifications.
            Supports lists using the syntax `devices[]=device1&devices[]=device2` or separated by commas.
          x-ms-summary: Devices
          example: device1,device2,device3
          schema:
            type: string
        - in: query
          name: onlyScheduled
          description: > 
            Where to remove only scheduled notifications (i.e. not remove notifications that were already delivered).
          x-ms-summary: Remove Delivered
          example: true
          schema:
            type: boolean
            default: false
      responses:
        "204": { description: Success }
        "400": { $ref: "definitions.yaml#/components/responses/400" }
        "401": { $ref: "definitions.yaml#/components/responses/401" }
  /subscriptions:
    get:
      operationId: GetSubscriptions
      summary: Get a list of all online action subscriptions
      description: Gets a list of all active webhook subscriptions created from this API Key.
      tags:
        - Subscriptions
      x-ms-visibility: internal
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                items:
                  $ref: "components/schemas/subscriptions.yaml#/SubscriptionData"
                type: array
        "401":
          $ref: "definitions.yaml#/components/responses/401"
    post:
      operationId: ActionExecuted
      description: |
        Adds a webhook that is triggered when an online action is executed in Pushcut.
        If *isLocalUrl* is set to true, your device will trigger the webhook on its local network.
      tags:
        - Subscriptions
      summary: Subscribe to an online action
      requestBody:
        content:
          application/json:
            schema:
              $ref: "components/schemas/subscriptions.yaml#/Subscription"
        required: true
      responses:
        "200":
          description: Success
          headers:
            Location:
              schema:
                type: string
              description: "URI to the subscription"
          content:
            application/json:
              schema:
                properties:
                  id:
                    description: ID of the subscription
                    type: string
                    example: "1234567890abc"
                type: object
        "400": { $ref: "definitions.yaml#/components/responses/400" }
        "401": { $ref: "definitions.yaml#/components/responses/401" }
      callbacks:
        ActionExecuted:
          "{$request.body#/url}":
            post:
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: "components/schemas/subscriptions.yaml#/EventData"
              responses:
                200:
                  description: Success
    x-ms-notification-content:
      description: Details for Webhook
      schema:
        $ref: "components/schemas/subscriptions.yaml#/EventData"
  "/subscriptions/{subscriptionId}":
    delete:
      parameters:
        - in: path
          name: subscriptionId
          description: Id that was returned when creating the subscription.
          required: true
          schema:
            type: string
      operationId: DeleteSubscription
      description: Deletes a webhook subscription.
      summary: Remove an online action subscription
      tags:
        - Subscriptions
      responses:
        200:
          description: Success

        "401": { $ref: "definitions.yaml#/components/responses/401" }
      x-ms-visibility: internal
  /execute:
    post:
      description: Schedules an Automation Server action request. Specify either a shortcut name or a HomeKit scene.
      operationId: Execute
      summary: Execute an Automation Server action.
      tags:
        - Automation Server
      x-ms-visibility: important
      parameters:
        - description: Shortcut
          in: query
          name: shortcut
          required: false
          example: My Shortcut
          schema:
            type: string
        - description: HomeKit scene
          in: query
          name: homekit
          required: false
          example: Downstairs Lights On
          schema:
            type: string
        - description: Timeout in seconds, or 'nowait'
          in: query
          name: timeout
          required: false
          example: nowait
          schema:
            type: string
        - description: "Duration in which this request should be executed. Eg: 10s, 15m, 6h"
          in: query
          name: delay
          required: false
          example: 10s
          schema:
            type: string
        - description: "Only used for delayed requests. Use an identifier to overwrite or cancel a scheduled execution."
          in: query
          name: identifier
          required: false
          example: MyIdentifier
          schema:
            type: string
        - name: input
          in: query
          description: Value that is passed as input to the shortcut.
          schema:
            type: string
        - name: serverId
          in: query
          description: The ID or name of the Automation Server that should execute the action.
          schema:
            type: string
      requestBody:
        description: Pass an input or optional configuration with the request.
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "components/schemas/servers.yaml#/ExecuteShortcut"
                - $ref: "components/schemas/servers.yaml#/ExecuteHomeKit"
      responses:
        "200":
          description: Success
        "202":
          description: Accepted (when scheduled with 'nowait')
        "400": { $ref: "definitions.yaml#/components/responses/400" }
        "401": { $ref: "definitions.yaml#/components/responses/401" }
        "404": { $ref: "definitions.yaml#/components/responses/404" }
        "502": { $ref: "definitions.yaml#/components/responses/502" }
        "504": { $ref: "definitions.yaml#/components/responses/504" }
  /cancelExecution:
    post:
      description: Cancels an Automation Server requests that was scheduled for future execution.
      operationId: CancelExecution
      summary: Cancel a scheduled Automation Server action.
      tags:
        - Automation Server
      x-ms-visibility: important
      parameters:
        - description: "Identifier of the request."
          in: query
          name: identifier
          required: false
          example: MyIdentifier
          schema:
            type: string
      responses:
        "200":
          description: Success
        "400": { $ref: "definitions.yaml#/components/responses/400" }
        "401": { $ref: "definitions.yaml#/components/responses/401" }
  "/images/{imageName}":
    $ref: "paths/imagesUpload.yaml"
  "/images/{imageName}/move":
    $ref: "paths/imagesMove.yaml"
  /servers:
    $ref: "paths/servers.yaml"
  /loggedNotifications:
    $ref: "paths/loggedNotifications.yaml"

x-ms-capabilities:
  testConnection:
    operationId: GetDevices
    parameters: {}
security:
  - api_key: []
tags:
  - description: For sending smart notifications
    name: Notifications
  - description: For executing Automation Server actions
    name: Automation Server
  - description: For registering online actions
    name: Subscriptions

servers:
  - url: https://api.pushcut.io/v1
components:
  responses:
    NotificationSent:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
              - id
            properties:
              id:
                $ref: "components/schemas/notifications.yaml#/NotificationId"
              notificationId:
                type: string
                description: Identifier that uniquely identifies a notification on a device
                deprecated: true
    NotificationScheduled:
      description: Notification was successfully scheduled
      content:
        application/json:
          schema:
            type: object
            required:
              - id
              - scheduleTimestamp
            properties:
              id:
                $ref: "components/schemas/notifications.yaml#/NotificationId"
              scheduleTimestamp:
                $ref: "v1/definitions.yaml#/components/schemas/scheduleTimestamp"
  securitySchemes:
    api_key:
      description: API-Keys can be managed in the Account view of the Pushcut app.
      in: header
      name: API-Key
      type: apiKey