openapi: 3.0.3
info:
  title: Tomorrow.io Weather Alerts API
  description: Unified Tomorrow.io v4 HTTP API for weather and climate intelligence. Combines realtime observations, forecast timelines (minutely, hourly, daily, current), historical data up to 20 years, weather along a route, raster map tiles, plus management surfaces for Locations, Insights, Alerts, and Events.
  version: 4.0.1
  contact:
    name: Tomorrow.io Support
    url: https://www.tomorrow.io/support/
  license:
    name: Tomorrow.io Terms of Service
    url: https://www.tomorrow.io/terms-of-service/
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
- url: https://api.tomorrow.io/v4
  description: Tomorrow.io v4 production API
security:
- apiKeyQuery: []
tags:
- name: Alerts
  description: Persistent alerts linked to one or more locations with webhook delivery.
paths:
  /alerts:
    get:
      operationId: listAlerts
      summary: Tomorrow.io List Alerts
      description: Lists alerts configured for the authenticated account.
      tags:
      - Alerts
      responses:
        '200':
          description: Alerts list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
              examples:
                ListAlerts200Example:
                  summary: Default listAlerts 200 response
                  x-microcks-default: true
                  value:
                  - id: 6183d156022c1b0008686b14
                    name: Hail Watch — Northeast Region
                    description: example
                    insightIds:
                    - 6183d156022c1b00086860a1
                    notifications:
                    - type: webhook
                      url: https://hooks.example.com/tomorrow-alerts
                    active: true
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createAlert
      summary: Tomorrow.io Create Alert
      description: Creates an alert that links one or more insights to one or more locations and pushes activations to a webhook URL.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertCreateRequest'
            examples:
              CreateAlertRequestExample:
                summary: Default createAlert request
                x-microcks-default: true
                value:
                  name: Hail Watch — Northeast Region
                  description: example
                  insightIds:
                  - example
                  locationIds:
                  - example
                  notifications:
                  - type: webhook
                    url: https://example.com/path
                  active: true
      responses:
        '201':
          description: Alert created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
              examples:
                CreateAlert201Example:
                  summary: Default createAlert 201 response
                  x-microcks-default: true
                  value:
                    id: 6183d156022c1b0008686b14
                    name: Hail Watch — Northeast Region
                    description: example
                    insightIds:
                    - 6183d156022c1b00086860a1
                    notifications:
                    - type: webhook
                      url: https://hooks.example.com/tomorrow-alerts
                    active: true
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/{alertId}:
    parameters:
    - name: alertId
      in: path
      required: true
      schema:
        type: string
      example: 6183d156022c1b0008686b14
    get:
      operationId: getAlert
      summary: Tomorrow.io Get Alert
      description: Retrieves a single alert by ID.
      tags:
      - Alerts
      responses:
        '200':
          description: Alert detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
              examples:
                GetAlert200Example:
                  summary: Default getAlert 200 response
                  x-microcks-default: true
                  value:
                    id: 6183d156022c1b0008686b14
                    name: Hail Watch — Northeast Region
                    description: example
                    insightIds:
                    - 6183d156022c1b00086860a1
                    notifications:
                    - type: webhook
                      url: https://hooks.example.com/tomorrow-alerts
                    active: true
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateAlert
      summary: Tomorrow.io Update Alert
      description: Updates an existing alert.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertCreateRequest'
            examples:
              UpdateAlertRequestExample:
                summary: Default updateAlert request
                x-microcks-default: true
                value:
                  name: Hail Watch — Northeast Region
                  description: example
                  insightIds:
                  - example
                  locationIds:
                  - example
                  notifications:
                  - type: webhook
                    url: https://example.com/path
                  active: true
      responses:
        '200':
          description: Updated alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
              examples:
                UpdateAlert200Example:
                  summary: Default updateAlert 200 response
                  x-microcks-default: true
                  value:
                    id: 6183d156022c1b0008686b14
                    name: Hail Watch — Northeast Region
                    description: example
                    insightIds:
                    - 6183d156022c1b00086860a1
                    notifications:
                    - type: webhook
                      url: https://hooks.example.com/tomorrow-alerts
                    active: true
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteAlert
      summary: Tomorrow.io Delete Alert
      description: Deletes an alert by ID.
      tags:
      - Alerts
      responses:
        '204':
          description: Alert deleted.
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/{alertId}/locations:
    parameters:
    - name: alertId
      in: path
      required: true
      schema:
        type: string
      example: 6183d156022c1b0008686b14
    get:
      operationId: listAlertLocations
      summary: Tomorrow.io List Alert Locations
      description: Lists locations linked to an alert.
      tags:
      - Alerts
      responses:
        '200':
          description: Locations linked to the alert.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Location'
              examples:
                ListAlertLocations200Example:
                  summary: Default listAlertLocations 200 response
                  x-microcks-default: true
                  value:
                  - id: 6183d156022c1b0008685cc6
                    name: Boston HQ Rooftop
                    geometry:
                      type: Point
                      coordinates:
                      - -71.0466
                      - 42.3478
                    tags:
                    - field-asset
                    - rooftop
                    createdAt: '2026-05-30T12:34:56Z'
                    updatedAt: '2026-05-30T12:34:56Z'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/{alertId}/locations/link:
    parameters:
    - name: alertId
      in: path
      required: true
      schema:
        type: string
      example: 6183d156022c1b0008686b14
    post:
      operationId: linkAlertLocations
      summary: Tomorrow.io Link Alert Locations
      description: Links one or more locations to the alert.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertLocationLinkRequest'
            examples:
              LinkAlertLocationsRequestExample:
                summary: Default linkAlertLocations request
                x-microcks-default: true
                value:
                  locationIds:
                  - 6183d156022c1b0008685cc6
      responses:
        '200':
          description: Locations linked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleAck'
              examples:
                LinkAlertLocations200Example:
                  summary: Default linkAlertLocations 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Operation completed successfully.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/{alertId}/locations/unlink:
    parameters:
    - name: alertId
      in: path
      required: true
      schema:
        type: string
      example: 6183d156022c1b0008686b14
    post:
      operationId: unlinkAlertLocations
      summary: Tomorrow.io Unlink Alert Locations
      description: Unlinks one or more locations from the alert.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertLocationLinkRequest'
            examples:
              UnlinkAlertLocationsRequestExample:
                summary: Default unlinkAlertLocations request
                x-microcks-default: true
                value:
                  locationIds:
                  - 6183d156022c1b0008685cc6
      responses:
        '200':
          description: Locations unlinked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleAck'
              examples:
                UnlinkAlertLocations200Example:
                  summary: Default unlinkAlertLocations 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Operation completed successfully.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/{alertId}/activate:
    parameters:
    - name: alertId
      in: path
      required: true
      schema:
        type: string
      example: 6183d156022c1b0008686b14
    post:
      operationId: activateAlert
      summary: Tomorrow.io Activate Alert
      description: Marks an alert as active so its insights begin firing on linked locations.
      tags:
      - Alerts
      responses:
        '200':
          description: Alert activated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleAck'
              examples:
                ActivateAlert200Example:
                  summary: Default activateAlert 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Operation completed successfully.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alerts/{alertId}/deactivate:
    parameters:
    - name: alertId
      in: path
      required: true
      schema:
        type: string
      example: 6183d156022c1b0008686b14
    post:
      operationId: deactivateAlert
      summary: Tomorrow.io Deactivate Alert
      description: Marks an alert as inactive so its insights stop firing.
      tags:
      - Alerts
      responses:
        '200':
          description: Alert deactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleAck'
              examples:
                DeactivateAlert200Example:
                  summary: Default deactivateAlert 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Operation completed successfully.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Location:
      type: object
      description: A saved location resource.
      properties:
        id:
          type: string
          example: 6183d156022c1b0008685cc6
        name:
          type: string
          example: Boston HQ Rooftop
        geometry:
          $ref: '#/components/schemas/GeoJSONGeometry'
        tags:
          type: array
          items:
            type: string
          example:
          - field-asset
          - rooftop
        createdAt:
          type: string
          format: date-time
          example: '2026-05-30T12:34:56Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-05-30T12:34:56Z'
      required:
      - id
      - name
      - geometry
    AlertCreateRequest:
      type: object
      description: Payload to create or update an alert.
      properties:
        name:
          type: string
          example: Hail Watch — Northeast Region
        description:
          type: string
        insightIds:
          type: array
          items:
            type: string
        locationIds:
          type: array
          items:
            type: string
        notifications:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - webhook
              url:
                type: string
                format: uri
        active:
          type: boolean
          default: true
      required:
      - name
      - insightIds
    GeoJSONGeometry:
      type: object
      description: GeoJSON geometry — Point, LineString, or Polygon.
      properties:
        type:
          type: string
          enum:
          - Point
          - LineString
          - Polygon
          example: Point
        coordinates:
          type: array
          items: {}
          example:
          - -71.0466
          - 42.3478
      required:
      - type
      - coordinates
    SimpleAck:
      type: object
      description: Generic success acknowledgement.
      properties:
        status:
          type: string
          example: ok
        message:
          type: string
          example: Operation completed successfully.
    AlertLocationLinkRequest:
      type: object
      properties:
        locationIds:
          type: array
          items:
            type: string
          example:
          - 6183d156022c1b0008685cc6
      required:
      - locationIds
    Alert:
      type: object
      description: A persistent alert that fires insights over linked locations and pushes activations to a webhook.
      properties:
        id:
          type: string
          example: 6183d156022c1b0008686b14
        name:
          type: string
          example: Hail Watch — Northeast Region
        description:
          type: string
        insightIds:
          type: array
          items:
            type: string
          example:
          - 6183d156022c1b00086860a1
        notifications:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - webhook
                example: webhook
              url:
                type: string
                format: uri
                example: https://hooks.example.com/tomorrow-alerts
        active:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - insightIds
    Error:
      type: object
      description: Standard Tomorrow.io error envelope.
      properties:
        code:
          type: integer
          example: 400001
          description: Internal error code.
        type:
          type: string
          example: Invalid Body Parameters
          description: Short error type label.
        message:
          type: string
          example: The provided parameters are invalid.
          description: Human-readable error message.
      required:
      - code
      - type
      - message
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: Tomorrow.io API key passed as `apikey` query parameter. Obtain at https://app.tomorrow.io/development/keys.