openapi: 3.1.0
info:
  title: Appio REST API
  version: "1.0.0"
  description: |
    OpenAPI specification generated from the public docs at https://docs.appio.so/.
    Authentication uses a Bearer token. Most endpoints also require the X-Service-Id header.
    Example service id: svc_00dddddd000000ccccccssssss
servers:
  - url: https://api.appio.so
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Token validation and service status
  - name: Devices
    description: Manage devices subscribed to a service
  - name: Notifications
    description: Send and query notifications
paths:
  /hi:
    get:
      tags: [Health]
      summary: Validate token
      description: Returns HTTP 200 if the Bearer token is valid.
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: "👋"
  /v1/devices:
    get:
      tags: [Devices]
      summary: List devices subscribed to service
      parameters:
        - $ref: '#/components/parameters/ServiceHeader'
      responses:
        '200':
          description: List of devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
    delete:
      tags: [Devices]
      summary: Deactivate all devices for a user
      description: Deactivate all of a user’s devices for the current service.
      parameters:
        - $ref: '#/components/parameters/ServiceHeader'
        - in: query
          name: user_id
          required: true
          schema:
            type: string
          description: User identifier
      responses:
        '200':
          description: List of deactivated device ids
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      $ref: '#/components/schemas/Id'
  /v1/devices/{id}:
    parameters:
      - $ref: '#/components/parameters/DeviceId'
    get:
      tags: [Devices]
      summary: View device details
      parameters:
        - $ref: '#/components/parameters/ServiceHeader'
      responses:
        '200':
          description: Device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
    delete:
      tags: [Devices]
      summary: Deactivate device
      parameters:
        - $ref: '#/components/parameters/ServiceHeader'
      responses:
        '200':
          description: Deactivated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/Id'
  /v1/notifications:
    get:
      tags: [Notifications]
      summary: List notifications
      parameters:
        - $ref: '#/components/parameters/ServiceHeader'
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/NotificationStatus'
          description: Filter by status
        - in: query
          name: device_id
          schema:
            type: string
          description: Filter by device id. If both device_id and user_id are provided, only device_id is used.
        - in: query
          name: user_id
          schema:
            type: string
          description: Filter by user id
      responses:
        '200':
          description: List of notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notification'
    post:
      tags: [Notifications]
      summary: Send a notification
      description: |
        Sends a notification. If no query parameters are provided, the notification is sent to all active devices in the service.
        To target a specific user or device, provide user_id or device_id as query parameters. The device_id parameter takes precedence when both are present.
      parameters:
        - $ref: '#/components/parameters/ServiceHeader'
        - in: query
          name: user_id
          schema:
            type: string
          required: false
        - in: query
          name: device_id
          schema:
            type: string
          required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/Id'
  /v1/notifications/{id}:
    parameters:
      - $ref: '#/components/parameters/NotificationId'
    get:
      tags: [Notifications]
      summary: View notification details
      parameters:
        - $ref: '#/components/parameters/ServiceHeader'
      responses:
        '200':
          description: Notification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationWithStats'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    ServiceHeader:
      in: header
      name: X-Service-Id
      required: true
      description: Your service id, for example svc_00dddddd000000ccccccssssss.
      schema:
        type: string
    DeviceId:
      in: path
      name: id
      required: true
      schema:
        type: string
        pattern: '^dvc_'
    NotificationId:
      in: path
      name: id
      required: true
      schema:
        type: string
        pattern: '^ntf_'
  schemas:
    Id:
      type: string
    HexColor:
      type: string
      pattern: '^#([0-9a-fA-F]{6})$'
      example: "#0066cc"
    Device:
      type: object
      properties:
        id:
          type: string
          pattern: '^dvc_'
        user_id:
          type: string
        name:
          type: string
        platform:
          type: string
          description: Device platform
          enum: [ios, android]
        os_version:
          type: string
        model:
          type: string
        device_token:
          type: string
          description: APNs or FCM token
        notifications_enabled:
          type: boolean
        device_identifier:
          type: string
        marketing_name:
          type: string
    NotificationStatus:
      type: string
      enum: [created, queued, completed, failed, skipped]
    NotificationPayload:
      type: object
      required: [title, message]
      properties:
        title:
          type: string
          maxLength: 50
        message:
          type: string
          maxLength: 200
        link:
          type: string
          format: uri
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
          description: "Image url. Image dimension ratio 16/9, up to 3MB. Allowed formats: .gif, .jpg, .png, .webp."
    NotificationRequest:
      type: object
      required: [payload]
      properties:
        payload:
          $ref: '#/components/schemas/NotificationPayload'
        scheduled_at:
          type: string
          format: date-time
          description: RFC 3339 timestamp up to 30 days in the future
          nullable: true
    DeliveryStats:
      type: object
      properties:
        total:
          type: integer
        created:
          type: integer
        queued:
          type: integer
        completed:
          type: integer
        failed:
          type: integer
    Notification:
      type: object
      properties:
        id:
          type: string
          pattern: '^ntf_'
        service_id:
          type: string
          pattern: '^svc_'
        status:
          $ref: '#/components/schemas/NotificationStatus'
        payload:
          $ref: '#/components/schemas/NotificationPayload'
        scheduled_at:
          type: string
          format: date-time
          nullable: true
    NotificationWithStats:
      allOf:
        - $ref: '#/components/schemas/Notification'
        - type: object
          properties:
            delivery_stats:
              $ref: '#/components/schemas/DeliveryStats'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message
            data:
              type: object
              description: Additional error details
              nullable: true
x-tagGroups:
  - name: Public API
    tags: [Health, Devices, Notifications]