openapi: 3.0.1
info:
  title: Tive Public Alerts API
  description: Specification of the Tive Public API (v3) for real-time supply-chain and shipment visibility. The API lets you create and track shipments, manage trackers (devices), retrieve sensor data (location, temperature, humidity, pressure, light, motion, battery), configure alert presets, and manage webhooks. This document models documented, real endpoints; it is intentionally a small-but-real subset and avoids fabricating undocumented surface area.
  termsOfService: https://www.tive.com/terms
  contact:
    name: Tive Support
    url: https://support.tive.com
  version: '3.0'
servers:
- url: https://api.tive.com/public/v3
  description: Tive Public API v3 (production)
security:
- bearerAuth: []
tags:
- name: Alerts
paths:
  /alertPresets:
    get:
      operationId: listAlertPresets
      tags:
      - Alerts
      summary: List alert presets
      parameters:
      - $ref: '#/components/parameters/AccountIdHeader'
      responses:
        '200':
          description: A list of alert presets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AlertPreset'
    post:
      operationId: createAlertPreset
      tags:
      - Alerts
      summary: Create an alert preset
      parameters:
      - $ref: '#/components/parameters/AccountIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertPreset'
      responses:
        '200':
          description: The created alert preset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertPreset'
components:
  schemas:
    AlertPreset:
      type: object
      properties:
        alertPresetId:
          type: string
        name:
          type: string
        triggers:
          type: array
          items:
            $ref: '#/components/schemas/AlertTrigger'
    AlertTrigger:
      type: object
      properties:
        type:
          type: string
          description: Trigger type, e.g. high temperature or light detected.
        threshold:
          type: number
        notify:
          type: boolean
          description: Whether the trigger should send notifications.
  parameters:
    AccountIdHeader:
      name: x-tive-account-id
      in: header
      required: true
      schema:
        type: string
      description: The Tive account ID. Required by most non-authentication endpoints.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token obtained from POST /authenticate. Send it as ''Authorization: Bearer <token>''. Most endpoints additionally require the x-tive-account-id header.'