Tomorrow.io Insights API

openapi: 3.0.3
info:
  title: Tomorrow.io Weather Alerts Insights 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: Insights
  description: Define threshold rules over weather fields to detect business-significant events.
paths:
  /insights:
    get:
      operationId: listInsights
      summary: Tomorrow.io List Insights
      description: Lists user-defined and pre-defined insight definitions available to the account.
      tags:
      - Insights
      responses:
        '200':
          description: Insights list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Insight'
              examples:
                ListInsights200Example:
                  summary: Default listInsights 200 response
                  x-microcks-default: true
                  value:
                  - id: 6183d156022c1b00086860a1
                    name: High Wind
                    description: Sustained wind speed above 15 m/s.
                    conditions:
                    - field: windSpeed
                      operator: gt
                      value: 15
                    logical: and
                    timestep: 1h
                    units: metric
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createInsight
      summary: Tomorrow.io Create Insight
      description: Creates a new insight that defines a threshold rule over one or more weather data fields.
      tags:
      - Insights
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightCreateRequest'
            examples:
              CreateInsightRequestExample:
                summary: Default createInsight request
                x-microcks-default: true
                value:
                  name: example
                  description: example
                  conditions:
                  - field: windSpeed
                    operator: gt
                    value: 15
                  logical: and
                  timestep: 1h
                  units: metric
      responses:
        '201':
          description: Insight created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Insight'
              examples:
                CreateInsight201Example:
                  summary: Default createInsight 201 response
                  x-microcks-default: true
                  value:
                    id: 6183d156022c1b00086860a1
                    name: High Wind
                    description: Sustained wind speed above 15 m/s.
                    conditions:
                    - field: windSpeed
                      operator: gt
                      value: 15
                    logical: and
                    timestep: 1h
                    units: metric
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /insights/{insightId}:
    parameters:
    - name: insightId
      in: path
      required: true
      schema:
        type: string
      example: 6183d156022c1b00086860a1
    get:
      operationId: getInsight
      summary: Tomorrow.io Get Insight
      description: Retrieves a single insight by ID.
      tags:
      - Insights
      responses:
        '200':
          description: Insight detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Insight'
              examples:
                GetInsight200Example:
                  summary: Default getInsight 200 response
                  x-microcks-default: true
                  value:
                    id: 6183d156022c1b00086860a1
                    name: High Wind
                    description: Sustained wind speed above 15 m/s.
                    conditions:
                    - field: windSpeed
                      operator: gt
                      value: 15
                    logical: and
                    timestep: 1h
                    units: metric
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateInsight
      summary: Tomorrow.io Update Insight
      description: Updates an existing insight.
      tags:
      - Insights
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightCreateRequest'
            examples:
              UpdateInsightRequestExample:
                summary: Default updateInsight request
                x-microcks-default: true
                value:
                  name: example
                  description: example
                  conditions:
                  - field: windSpeed
                    operator: gt
                    value: 15
                  logical: and
                  timestep: 1h
                  units: metric
      responses:
        '200':
          description: Updated insight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Insight'
              examples:
                UpdateInsight200Example:
                  summary: Default updateInsight 200 response
                  x-microcks-default: true
                  value:
                    id: 6183d156022c1b00086860a1
                    name: High Wind
                    description: Sustained wind speed above 15 m/s.
                    conditions:
                    - field: windSpeed
                      operator: gt
                      value: 15
                    logical: and
                    timestep: 1h
                    units: metric
                    createdAt: '2026-05-30T13:00:00Z'
                    updatedAt: '2026-05-30T13:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteInsight
      summary: Tomorrow.io Delete Insight
      description: Deletes an insight by ID.
      tags:
      - Insights
      responses:
        '204':
          description: Insight deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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:
    InsightCreateRequest:
      type: object
      description: Payload to create or update an insight.
      properties:
        name:
          type: string
        description:
          type: string
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/InsightCondition'
        logical:
          type: string
          enum:
          - and
          - or
          default: and
        timestep:
          type: string
          example: 1h
        units:
          type: string
          enum:
          - metric
          - imperial
      required:
      - name
      - conditions
    Insight:
      type: object
      description: A named threshold definition over one or more weather fields.
      properties:
        id:
          type: string
          example: 6183d156022c1b00086860a1
        name:
          type: string
          example: High Wind
        description:
          type: string
          example: Sustained wind speed above 15 m/s.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/InsightCondition'
        logical:
          type: string
          enum:
          - and
          - or
          default: and
        timestep:
          type: string
          example: 1h
        units:
          type: string
          enum:
          - metric
          - imperial
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - conditions
    InsightCondition:
      type: object
      description: A single condition that must hold for an insight to fire.
      properties:
        field:
          type: string
          example: windSpeed
        operator:
          type: string
          enum:
          - eq
          - neq
          - gt
          - gte
          - lt
          - lte
          example: gt
        value:
          type: number
          format: double
          example: 15
      required:
      - field
      - operator
      - value
    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.