iotPush API

openapi: 3.1.0
info:
  title: iotPush API
  version: '2026-11-12'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-12: 25 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; iotPush has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 4
    documentation: 21
    pages-with-code: 2
    pages-read: 2
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-12'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://www.iotpush.com/docs
  - https://github.com/dasecure/iotpush-examples
servers:
- url: https://iotpush.com
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://github.com/dasecure/iotpush-examples
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl/ask-and-wait.sh \n Ask Approve/Reject and block; exits 0 only on approve (curl + jq) \n python/send.py \n Send a JSON push,\
          \ standard library only (Python 3.9+) \n python/ask_and_wait.py \n Ask and wait, standard library only \n node/send.mjs \n Send a JSON\
          \ push with built-in fetch , no dependencies (Node 18.3+) \n node/ask-and-wait.mjs \n Ask and wait with built-in fetch \n esp32/ \n\
          \ ESP32 sketch: push "
  /api/1/messages.json:
    post:
      operationId: post_api_1_messages_json
      tags:
      - Api
      summary: Pushover‑compatible endpoint
      x-source: https://www.iotpush.com/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApi1MessagesJsonRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/action:
    post:
      operationId: post_api_action
      tags:
      - Api
      summary: Report Action
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiActionRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/devices:
    get:
      operationId: get_api_devices
      tags:
      - Api
      summary: List devices
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_devices
      tags:
      - Api
      summary: Register a device
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiDevicesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/push/{topic}:
    get:
      operationId: get_api_push_topic
      tags:
      - Api
      summary: GET /api/push/{topic}
      x-source: https://github.com/dasecure/iotpush-examples
      parameters:
      - name: topic
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://www.iotpush.com/api/push/YOUR_TOPIC  -H \" Authorization: Bearer YOUR_TOPIC_KEY \"  -H \" Content-Type: text/plain\
          \ \"  --data-binary \" Backup finished \" \n The plain-text body is the message. Public topics need no Authorization header.\nThe response\
          \ JSON includes a receipt_id . \n Examples \n Path \n What it shows "
    post:
      operationId: post_api_push_topic
      tags:
      - Api
      summary: Send a push notification to all subscribers of a topic.
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: topic
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
        description: Bearer token = your topic API key (private topics).
      - name: Title
        in: header
        required: false
        schema:
          type: string
        description: Notification title shown in bold.
      - name: Priority
        in: header
        required: false
        schema:
          type: string
        description: low · normal (default) · high · urgent
      - name: Tags
        in: header
        required: false
        schema:
          type: string
        description: Comma-separated tags.
      - name: Click-Url
        in: header
        required: false
        schema:
          type: string
        description: URL to open when the notification is tapped.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiPushTopicRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiPushTopicResponse'
      x-evidence:
        kind: documentation
  /api/pushover:
    post:
      operationId: post_api_pushover
      tags:
      - Api
      summary: Pushover‑compatible endpoint (alternative URL)
      x-source: https://www.iotpush.com/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiPushoverRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/receipts:
    get:
      operationId: get_api_receipts
      tags:
      - Api
      summary: List receipts
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: topic_id
        in: query
        required: false
        schema:
          type: string
        description: Filter to a single topic.
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: queued·delivered·read·acted·expired·failed
      - name: since
        in: query
        required: false
        schema:
          type: string
        description: ISO 8601 timestamp – only return receipts after this time.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor (created_at of last item).
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Max results per page (default 50, max 100).
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/receipts/{receiptId}:
    get:
      operationId: get_api_receipts_receiptId
      tags:
      - Api
      summary: Get a receipt
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: receiptId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
        description: 'Bearer USER_SESSION_TOKEN or X-Api-Key: TOPIC_API_KEY'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiReceiptsReceiptidResponse'
      x-evidence:
        kind: documentation
  /api/topics:
    get:
      operationId: get_api_topics
      tags:
      - Api
      summary: List all your topics
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_topics
      tags:
      - Api
      summary: Create a new topic
      x-source: https://www.iotpush.com/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiTopicsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/topics/{id}:
    delete:
      operationId: delete_api_topics_id
      tags:
      - Api
      summary: Delete a topic and all its messages
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_api_topics_id
      tags:
      - Api
      summary: Update topic name, description, or privacy
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchApiTopicsIdRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/links:
    get:
      operationId: get_api_v1_links
      tags:
      - Api
      summary: List links
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: source
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_links
      tags:
      - Api
      summary: Link a resource → a topic, phones already subscribed
      x-source: https://www.iotpush.com/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1LinksRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1LinksResponse'
      x-evidence:
        kind: documentation
  /api/v1/links/{id}:
    delete:
      operationId: delete_api_v1_links_id
      tags:
      - Api
      summary: Unlinks (the topic stays)
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/questions:
    post:
      operationId: post_api_v1_questions
      tags:
      - Api
      summary: POST /api/v1/questions with question , and optionally title , kind , topic , timeout_s (10–86400, default 300) and idempotency_key
        . Returns question_id .
      x-source: https://github.com/dasecure/iotpush-examples
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1QuestionsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1QuestionsResponse'
      x-evidence:
        kind: documentation
  /api/v1/questions/{questionId}/cancel:
    post:
      operationId: post_api_v1_questions_questionId_cancel
      tags:
      - Api
      summary: POST /api/v1/questions/{question_id}/cancel withdraws it.
      x-source: https://github.com/dasecure/iotpush-examples
      parameters:
      - name: questionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/questions/{questionId}/wait:
    get:
      operationId: get_api_v1_questions_questionId_wait
      tags:
      - Api
      summary: GET /api/v1/questions/{question_id}/wait?timeout=30 (up to 55 s). Repeat while status is pending .
      x-source: https://github.com/dasecure/iotpush-examples
      parameters:
      - name: questionId
        in: path
        required: true
        schema:
          type: string
      - name: timeout
        in: query
        required: false
        schema:
          type: integer
        description: seconds, up to 55
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/webhooks:
    get:
      operationId: get_api_webhooks
      tags:
      - Api
      summary: List all your webhooks
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_webhooks
      tags:
      - Api
      summary: Create a webhook
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiWebhooksRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/webhooks/{id}:
    delete:
      operationId: delete_api_webhooks_id
      tags:
      - Api
      summary: Delete a webhook
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_api_webhooks_id
      tags:
      - Api
      summary: Update url, events, active, or topic_ids
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchApiWebhooksIdRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/webhooks/{id}/test:
    post:
      operationId: post_api_webhooks_id_test
      tags:
      - Api
      summary: Send a test event to the webhook URL
      x-source: https://www.iotpush.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer USER_SESSION_TOKEN
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostApi1MessagesJsonRequest:
      type: object
      properties:
        token:
          type: string
          description: Your iotpush topic API key
        user:
          type: string
          description: Topic name (optional if token is unique)
        message:
          type: string
          description: Notification message
        title:
          type: string
          description: Notification title
        url:
          type: string
          description: Click URL
        priority:
          type: integer
          description: -2 to 2
      required:
      - token
      - user
      - message
    PostApiActionRequest:
      type: object
      properties:
        message_id:
          type: string
          description: ID of the message the action belongs to.
        action_id:
          type: string
          description: ID of the action that was tapped.
        reply_text:
          type: string
          description: Text entered by user for reply-type actions.
        device_id:
          type: string
          description: Device ID for attribution.
      required:
      - message_id
      - action_id
    PostApiDevicesRequest:
      type: object
      properties:
        push_token:
          type: string
          description: Expo push token (ExponentPushToken[...]).
        platform:
          type: string
          description: ios·android·web.
        device_name:
          type: string
          description: Human-readable name.
        app_version:
          type: string
          description: App version string.
      required:
      - push_token
      - platform
    PostApiPushTopicRequest:
      type: object
      properties:
        message:
          type: string
          description: The notification body text.
        title:
          type: string
          description: Notification title shown in bold.
        priority:
          type: string
          description: low · normal (default) · high · urgent
        tags:
          type: string
          description: Comma-separated tags, e.g. "sensor,alert".
        click_url:
          type: string
          description: URL to open when the notification is tapped.
        actions:
          type: array
          description: Interactive action buttons.
        callback_url:
          type: string
          description: Webhook URL called when an action is tapped.
      required:
      - message
    PostApiPushTopicResponse:
      type: object
      properties:
        success:
          type: boolean
        id:
          type: string
        receipt_id:
          type: string
        topic:
          type: string
        timestamp:
          type: string
        subscribers:
          type: integer
    PostApiPushoverRequest:
      type: object
      properties:
        token:
          type: string
          description: Your iotpush topic API key
        user:
          type: string
          description: Topic name (optional if token is unique)
        message:
          type: string
          description: Notification message
        title:
          type: string
          description: Notification title
        url:
          type: string
          description: Click URL
        priority:
          type: integer
          description: -2 to 2
      required:
      - token
      - user
      - message
    GetApiReceiptsReceiptidResponse:
      type: object
      properties:
        receipt_id:
          type: string
        message_id:
          type: string
        topic_id:
          type: string
        status:
          type: string
        delivered_count:
          type: integer
        read_count:
          type: integer
        acted_count:
          type: integer
        actions_taken:
          type: array
        created_at:
          type: string
        updated_at:
          type: string
    PostApiTopicsRequest:
      type: object
      properties:
        name:
          type: string
          description: URL‑safe slug
        description:
          type: string
          description: Topic description
        is_private:
          type: boolean
          description: If true, API key required to push
      required:
      - name
    PatchApiTopicsIdRequest:
      type: object
      properties:
        name:
          type: string
          description: URL‑safe slug
        description:
          type: string
          description: Topic description
        is_private:
          type: boolean
          description: If true, API key required to push
    PostApiV1LinksRequest:
      type: object
      properties:
        source:
          type: string
          description: Source identifier
        resource:
          type: string
          description: Resource identifier
        label:
          type: string
          description: Human‑readable label
      required:
      - source
      - resource
      - label
    PostApiV1LinksResponse:
      type: object
      properties:
        link_id:
          type: string
        topic:
          type: string
        topic_id:
          type: string
        publish_url:
          type: string
        subscribed_devices:
          type: integer
        devices_total:
          type: integer
        created:
          type: boolean
    PostApiV1QuestionsRequest:
      type: object
      properties:
        question:
          type: string
        title:
          type: string
        kind:
          type: string
        topic:
          type: string
        timeout_s:
          type: integer
          description: 10–86400, default 300
        idempotency_key:
          type: string
      required:
      - question
    PostApiV1QuestionsResponse:
      type: object
      properties:
        question_id:
          type: string
    PostApiWebhooksRequest:
      type: object
      properties:
        url:
          type: string
          description: HTTPS endpoint to receive events.
        events:
          type: array
          description: List of events (action, delivered, read, expired, all).
        topic_ids:
          type: array
          description: Limit to specific topics (empty = all topics).
      required:
      - url
      - events
    PatchApiWebhooksIdRequest:
      type: object
      properties:
        url:
          type: string
          description: New webhook URL.
        events:
          type: array
          description: Updated list of events.
        active:
          type: boolean
          description: Enable or disable webhook.
        topic_ids:
          type: array
          description: Updated topic filters.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api