openapi: 3.2.0
info:
  title: Latitude Incidents API
  version: v1
  description: Open-source AI agent monitoring platform. Full observability into what's failing in production. Discover underlying issues, get alerts when something breaks and verify your fix worked.
  servers:
  - url: https://api.latitude.so
    description: Production
servers:
- url: https://api.latitude.so
tags:
- name: Incidents
paths:
  /v1/projects/{projectSlug}/incidents:
    get:
      tags:
      - Incidents
      x-fern-sdk-group-name: incidents
      x-fern-sdk-method-name: list
      summary: List project incidents
      description: Returns incidents in the project, ordered from oldest to newest. The time window defaults to the trailing 7 days.
      security:
      - ApiKeyAuth: []
      operationId: listIncidents
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          format: date-time
          description: Lower bound (inclusive) of the time window. Returns incidents whose lifetime overlaps `[fromIso, toIso]`. Defaults to 7 days before `toIso`.
        required: false
        description: Lower bound (inclusive) of the time window. Returns incidents whose lifetime overlaps `[fromIso, toIso]`. Defaults to 7 days before `toIso`.
        name: fromIso
        in: query
      - schema:
          type: string
          format: date-time
          description: Upper bound (inclusive) of the time window. Defaults to now.
        required: false
        description: Upper bound (inclusive) of the time window. Defaults to now.
        name: toIso
        in: query
      - schema:
          type: string
          enum:
          - monitor
          - signal
          description: 'Restrict to incidents triggered by this source type: `monitor` or `signal`.'
        required: false
        description: 'Restrict to incidents triggered by this source type: `monitor` or `signal`.'
        name: source_type
        in: query
      - schema:
          type: string
          minLength: 24
          maxLength: 24
          description: Restrict to incidents tied to one source entity id.
        required: false
        description: Restrict to incidents tied to one source entity id.
        name: source_id
        in: query
      - schema:
          type: array
          items:
            type: string
            enum:
            - low
            - medium
            - high
            - urgent
          description: Restrict to incidents whose severity matches any value in this list.
        required: false
        description: Restrict to incidents whose severity matches any value in this list.
        name: severities
        in: query
      responses:
        '200':
          description: Matching incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListIncidentsResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{projectSlug}/incidents/{incidentId}:
    post:
      tags:
      - Incidents
      x-fern-sdk-group-name: incidents
      x-fern-sdk-method-name: resolve
      summary: Resolve incident
      description: Resolves (closes) an ongoing incident. An already-closed incident is returned unchanged. If the incident's condition triggers again, a new incident will be opened.
      security:
      - ApiKeyAuth: []
      operationId: resolveIncident
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          minLength: 24
          maxLength: 24
          description: Incident identifier.
        required: true
        description: Incident identifier.
        name: incidentId
        in: path
      responses:
        '200':
          description: Resolved incident
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    Incident:
      type: object
      properties:
        id:
          type: string
          minLength: 24
          maxLength: 24
          description: Stable incident identifier.
        organizationId:
          type: string
          minLength: 24
          maxLength: 24
          description: Organization that owns this incident.
        projectId:
          type: string
          minLength: 24
          maxLength: 24
          description: Project this incident belongs to.
        sourceType:
          type: string
          enum:
          - monitor
          - signal
          description: 'Kind of entity that triggered the incident: `signal` or `monitor`.'
        sourceId:
          type: string
          minLength: 24
          maxLength: 24
          description: Id of the entity that triggered the incident (matches `sourceType`).
        severity:
          type: string
          enum:
          - low
          - medium
          - high
          - urgent
          description: 'Severity bucket assigned to the incident: `low`, `medium`, `high`, or `urgent`.'
        startedAt:
          type: string
          description: ISO-8601 timestamp at which the incident opened.
        endedAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp at which the incident closed, or `null` if still open.
        createdAt:
          type: string
          description: ISO-8601 timestamp at which the incident row was created.
        condition:
          anyOf:
          - $ref: '#/components/schemas/AlertThresholdCondition'
          - $ref: '#/components/schemas/AlertEscalatingCondition'
          - nullable: true
          description: The monitor rule configuration when the incident opened, or `null` for signal incidents and match monitors.
      required:
      - id
      - organizationId
      - projectId
      - sourceType
      - sourceId
      - severity
      - startedAt
      - endedAt
      - createdAt
      - condition
    AlertEscalatingCondition:
      type: object
      properties:
        trigger:
          type: string
          enum:
          - escalating
          description: Opens when the monitor target is escalating or sustained.
        metric:
          $ref: '#/components/schemas/MonitorMetric'
        threshold:
          allOf:
          - $ref: '#/components/schemas/AlertMetricThreshold'
          - description: How the metric is compared when threshold-based.
        direction:
          type: string
          enum:
          - above
          - below
          description: Direction that opens the incident. Defaults to `above` when omitted.
        sensitivity:
          type: integer
          minimum: 1
          maximum: 6
          description: Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 when omitted.
        window:
          type: object
          properties:
            minutes:
              type: integer
              minimum: 5
              description: How long the threshold must stay crossed before the incident opens. Minimum 5.
          required:
          - minutes
          description: Sustained-condition window.
      required:
      - trigger
      - metric
      - window
    AlertBaseline:
      type: object
      properties:
        kind:
          type: string
          enum:
          - average
          - period
          description: How the comparison rate is computed. `average` is the rolling rate over the last `lookback`; `period` is the equal-length window immediately before it (e.g. `lookback` of 1 day compares against yesterday) for daily/weekly seasonality.
        lookback:
          $ref: '#/components/schemas/AlertDuration'
      required:
      - kind
      - lookback
      description: Fixed-window baseline the current rate is compared against.
    AlertThresholdCondition:
      type: object
      properties:
        trigger:
          type: string
          enum:
          - threshold
          description: Opens once the measured value crosses the threshold.
        metric:
          $ref: '#/components/schemas/MonitorMetric'
        threshold:
          $ref: '#/components/schemas/AlertMetricThreshold'
        direction:
          type: string
          enum:
          - above
          - below
          description: Direction that opens the incident. Defaults to `above` when omitted.
      required:
      - trigger
      - metric
      - threshold
    ListIncidentsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Incident'
          description: Incidents matching the filters, ordered by `startedAt` ascending.
      required:
      - items
    MonitorMetric:
      oneOf:
      - type: object
        properties:
          kind:
            type: string
            enum:
            - count
            description: Count matching events in each evaluation bucket.
        required:
        - kind
      - type: object
        properties:
          kind:
            type: string
            enum:
            - errorRate
            description: Measure the fraction of matching events that errored.
        required:
        - kind
      - type: object
        properties:
          kind:
            type: string
            enum:
            - cacheHitRate
            description: Token-weighted prompt-cache hit rate (cache-read tokens over total input-side tokens), a 0..1 fraction.
        required:
        - kind
      - type: object
        properties:
          kind:
            type: string
            enum:
            - avg
            description: Average a numeric field over matching events.
          field:
            type: string
            enum:
            - duration
            - cost
            - tokens
            description: Numeric field to aggregate.
        required:
        - kind
        - field
      - type: object
        properties:
          kind:
            type: string
            enum:
            - sum
            description: Sum a numeric field over matching events.
          field:
            type: string
            enum:
            - duration
            - cost
            - tokens
            description: Numeric field to aggregate.
        required:
        - kind
        - field
      - type: object
        properties:
          kind:
            type: string
            enum:
            - min
            description: Find the minimum numeric field value over matching events.
          field:
            type: string
            enum:
            - duration
            - cost
            - tokens
            description: Numeric field to aggregate.
        required:
        - kind
        - field
      - type: object
        properties:
          kind:
            type: string
            enum:
            - max
            description: Find the maximum numeric field value over matching events.
          field:
            type: string
            enum:
            - duration
            - cost
            - tokens
            description: Numeric field to aggregate.
        required:
        - kind
        - field
      - type: object
        properties:
          kind:
            type: string
            enum:
            - median
            description: Find the median numeric field value over matching events.
          field:
            type: string
            enum:
            - duration
            - cost
            - tokens
            description: Numeric field to aggregate.
        required:
        - kind
        - field
      description: Metric measured over the monitor target.
    AlertMetricThreshold:
      oneOf:
      - type: object
        properties:
          mode:
            type: string
            enum:
            - absolute
            description: Compare the metric against a fixed value; read `value`.
          value:
            type: number
            minimum: 0
            exclusiveMinimum: true
            description: Metric value that opens the incident.
        required:
        - mode
        - value
      - type: object
        properties:
          mode:
            type: string
            enum:
            - multiplier
            description: Compare the metric rate against `factor × baseline`; read `factor` and `baseline`.
          factor:
            type: number
            minimum: 0
            exclusiveMinimum: true
            description: Multiple of the baseline rate that opens the incident (e.g. `3` = 3×).
          baseline:
            $ref: '#/components/schemas/AlertBaseline'
        required:
        - mode
        - factor
        - baseline
      - type: object
        properties:
          mode:
            type: string
            enum:
            - expected
            description: Compare against the seasonally-learned expected value for this time of day/week.
          sensitivity:
            type: integer
            minimum: 1
            maximum: 6
            description: Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 when omitted.
        required:
        - mode
      description: How the metric is compared.
    AlertDuration:
      oneOf:
      - type: object
        properties:
          unit:
            type: string
            enum:
            - minutes
            description: The duration is expressed in whole minutes; read `minutes`.
          minutes:
            type: number
            minimum: 0
            exclusiveMinimum: true
            description: Number of minutes.
        required:
        - unit
        - minutes
      - type: object
        properties:
          unit:
            type: string
            enum:
            - hours
            description: The duration is expressed in whole hours; read `hours`.
          hours:
            type: number
            minimum: 0
            exclusiveMinimum: true
            description: Number of hours.
        required:
        - unit
        - hours
      - type: object
        properties:
          unit:
            type: string
            enum:
            - days
            description: The duration is expressed in whole days; read `days`.
          days:
            type: number
            minimum: 0
            exclusiveMinimum: true
            description: Number of days.
        required:
        - unit
        - days
      description: Length of the window used to compute the baseline rate.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Organization-scoped API key, sent as `Authorization: Bearer <key>`.'
      x-fern-bearer:
        name: apiKey
        env: LATITUDE_API_KEY