> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an incident

> Omitted fields keep their current value, including `customer_targeting`. On a customer-scoped incident, targeting must be `selected` with exactly the visible customers.



## OpenAPI

````yaml api-reference/openapi.json PATCH /incidents/{id}
openapi: 3.1.0
info:
  title: Observer API
  version: 1.2.0
  description: >-
    Public API for Observer: read services, metrics, SLOs and SLA statements;
    manage incidents, maintenance windows, manual metric status, config as code
    and Observer Agents. Bearer-auth via API keys (obs_pub_…), scoped per key.
    RFC 7807 problem-detail errors. Cursor pagination. Rate limits are per
    organization. Every date-time value is RFC 3339 in UTC with millisecond
    precision (`2026-01-31T12:00:00.000Z`).
servers:
  - url: https://use.observer/api/v1
security:
  - bearerAuth: []
paths:
  /incidents/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Incident id.
        schema:
          type: string
          format: uuid
    patch:
      tags:
        - incidents
      summary: >-
        Patch incident (title, severity, affected services, visibility, customer
        targeting)
      description: >-
        Omitted fields keep their current value, including `customer_targeting`.
        On a customer-scoped incident, targeting must be `selected` with exactly
        the visible customers.
      operationId: patchIncident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentPatchRequest'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Daily-Limit:
              $ref: '#/components/headers/X-RateLimit-Daily-Limit'
            X-RateLimit-Daily-Remaining:
              $ref: '#/components/headers/X-RateLimit-Daily-Remaining'
            X-RateLimit-Daily-Reset:
              $ref: '#/components/headers/X-RateLimit-Daily-Reset'
        '400':
          description: >-
            `invalid_json`: the body is not a JSON object. `invalid_title`:
            `title` is sent but blank (a title can be changed, not cleared).
            `invalid_severity`: `severity` is not an accepted value.
            `invalid_postmortem_url`: `postmortem_url` must be an http(s) URL.
            `invalid_customer_targeting`: `customer_targeting` is malformed
            (unknown `mode`, `customers` missing for `selected` or present for
            `none`/`all`, more than 500 entries). The body carries `errors`, a
            list of `{ path, message }`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: >-
            `unauthenticated`: no bearer token was sent, or the key is invalid
            or revoked. `detail` distinguishes the two.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: >-
            `forbidden`: the key does not carry the scope this endpoint
            requires. `plan_does_not_permit_api`: the organization's plan does
            not include the public API.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: >-
            `not_found`: no incident with that id is available to this key. One
            owned by another organization, or an id that is not a valid UUID,
            returns the same response, so a 404 does not confirm that the id is
            unused.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: >-
            `unknown_services`: an `affected_services` value is not the id of a
            service in your organization (unknown, another organization's, or
            not a uuid); the body's `unknown_services` echoes only the unmatched
            values and nothing is written. `unknown_customers`: a
            `visible_to_customer_ids` or `customer_targeting.customers` value
            matches no customer in your organization; the body's
            `unknown_customers` echoes only the unmatched values.
            `customer_targeting_conflict`: the update is customer-scoped and
            `customer_targeting` is not `selected` with exactly its visible
            customers.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: >-
            `rate_limited`: the organization's per-minute or daily request limit
            is used up (`limit.window` says which). Limits are per organization,
            shared by every key. The response carries `Retry-After` and
            `retry_after`, in seconds.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Daily-Limit:
              $ref: '#/components/headers/X-RateLimit-Daily-Limit'
            X-RateLimit-Daily-Remaining:
              $ref: '#/components/headers/X-RateLimit-Daily-Remaining'
            X-RateLimit-Daily-Reset:
              $ref: '#/components/headers/X-RateLimit-Daily-Reset'
        '500':
          description: '`internal_error`: an unhandled server error. Safe to retry.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth:
            - write:incidents
components:
  schemas:
    IncidentPatchRequest:
      type: object
      properties:
        title:
          type: string
        severity:
          type: string
          enum:
            - minor
            - major
            - critical
        affected_services:
          type: array
          items:
            type: string
            format: uuid
        visible_to_customer_ids:
          type: array
          items:
            type: string
            format: uuid
        customer_targeting:
          $ref: '#/components/schemas/CustomerTargetingInput'
        postmortem_url:
          type:
            - string
            - 'null'
          format: uri
    Incident:
      type: object
      required:
        - id
        - title
        - type
        - created_at
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        type:
          type: string
          enum:
            - Incident
            - Maintenance
        severity:
          type:
            - string
            - 'null'
          enum:
            - minor
            - major
            - critical
            - maintenance
            - null
        state:
          type: string
          enum:
            - draft
            - published
            - resolved
            - scheduled
            - in_progress
            - completed
            - canceled
        published_at:
          type:
            - string
            - 'null'
          format: date-time
        resolved_at:
          type:
            - string
            - 'null'
          format: date-time
        scheduled_start_at:
          type:
            - string
            - 'null'
          format: date-time
        scheduled_end_at:
          type:
            - string
            - 'null'
          format: date-time
        actual_start_at:
          type:
            - string
            - 'null'
          format: date-time
        actual_end_at:
          type:
            - string
            - 'null'
          format: date-time
        canceled_at:
          type:
            - string
            - 'null'
          format: date-time
        postmortem_url:
          type:
            - string
            - 'null'
          format: uri
        affected_services:
          type: array
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
        visible_to_customer_ids:
          type: array
          items:
            type: string
            format: uuid
        customer_targeting:
          $ref: '#/components/schemas/CustomerTargeting'
        messages:
          type: array
          description: The timeline, oldest first (by `date`, then `id`).
          items:
            type: object
            required:
              - id
              - type
              - description
              - date
            properties:
              id:
                type: string
                format: uuid
              type:
                type: string
                enum:
                  - Investigating
                  - Information
                  - Identified
                  - Resolved
              description:
                type: string
              date:
                type: string
                format: date-time
        created_at:
          type: string
          format: date-time
    Problem:
      type: object
      required:
        - type
        - title
        - status
      example:
        type: https://docs.use.observer/api/getting-started/errors#forbidden
        title: forbidden
        status: 403
        detail: 'missing scope: write:incidents'
      properties:
        type:
          type: string
          format: uri
          description: Errors reference URI with the title token as the fragment.
          example: https://docs.use.observer/api/getting-started/errors#forbidden
        title:
          type: string
          description: Stable error token. Branch on this, not on detail.
        status:
          type: integer
        detail:
          type: string
          description: Human-readable explanation. Wording may change.
        retry_after:
          type: integer
          description: >-
            429 only: seconds until the exhausted window resets (mirrors
            Retry-After).
        limit:
          type: object
          description: '429 only: which organization limit was hit.'
          properties:
            scope:
              type: string
              enum:
                - organization
            window:
              type: string
              enum:
                - minute
                - day
            max:
              type: integer
            plan:
              type: string
        errors:
          type: array
          description: >-
            Validation failures (config_invalid, invalid_customer_targeting):
            one entry per problem.
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
        warnings:
          type: array
          description: >-
            config_invalid only: the same non-fatal warnings a successful apply
            returns.
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
        unknown_customers:
          type: array
          description: >-
            unknown_customers only: the submitted values that matched no
            customer in your organization.
          items:
            type: string
        unknown_services:
          type: array
          description: >-
            unknown_services only: the submitted `affected_services` values that
            matched no service in your organization.
          items: {}
        referenced_by:
          type: object
          description: >-
            in_use only: what depends on the object (slos, pages: lists of { id,
            config_key, name }; subscribers: a count).
        quota:
          type: object
          description: >-
            quota_exceeded / feature_locked on a create, item_suspended_plan on
            a write to a suspended item: the plan limit involved.
          properties:
            capability:
              type: string
            used:
              type:
                - integer
                - 'null'
            cap:
              type:
                - integer
                - 'null'
            plan:
              type:
                - string
                - 'null'
        upgrade:
          type: object
          description: >-
            Plan-limit problems only, when a higher plan lifts the limit: the
            smallest such plan and the pricing page.
          properties:
            plan:
              type: string
            label:
              type: string
            url:
              type: string
              format: uri
    CustomerTargetingInput:
      type: object
      required:
        - mode
      additionalProperties: false
      description: >-
        Affected customers. mode none = public subscribers only; selected = the
        listed customers; all = every customer. Each customers entry is a
        customer id (uuid) or the customer's external_id, resolved within your
        organization; unknown values are rejected with 422 unknown_customers.
        customers is required (non-empty) for selected and not allowed
        otherwise. On a customer-scoped update (visible_to_customer_ids set) the
        targeting must be selected with exactly the visible customers.
      properties:
        mode:
          type: string
          enum:
            - none
            - selected
            - all
        customers:
          type: array
          items:
            type: string
            minLength: 1
          maxItems: 500
        notify_customer_subscribers:
          type: boolean
          default: true
          description: >-
            Email the targeted customers' linked subscribers about a public
            update.
    CustomerTargeting:
      type: object
      description: >-
        Which customers the update affects: mode (none, selected or all),
        customers (empty unless mode is selected), and whether their linked
        subscribers are emailed.
      required:
        - mode
        - customers
        - notify_customer_subscribers
      properties:
        mode:
          type: string
          enum:
            - none
            - selected
            - all
        customers:
          type: array
          items:
            type: object
            required:
              - id
              - external_id
              - name
            properties:
              id:
                type: string
                format: uuid
              external_id:
                type:
                  - string
                  - 'null'
              name:
                type: string
        notify_customer_subscribers:
          type: boolean
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per minute for the organization.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Seconds until the per-minute window resets.
      schema:
        type: integer
    X-RateLimit-Daily-Limit:
      description: Requests allowed per UTC day for the organization.
      schema:
        type: integer
    X-RateLimit-Daily-Remaining:
      description: Requests left today (UTC).
      schema:
        type: integer
    X-RateLimit-Daily-Reset:
      description: Seconds until the daily quota resets (UTC midnight).
      schema:
        type: integer
    Retry-After:
      description: '429 only: seconds to wait before retrying.'
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: obs_pub_
      description: >-
        An organization API key (obs_pub_…) sent as `Authorization: Bearer
        <key>`. Each key carries scopes; an endpoint lists the scope it needs.
        `read:change_events` is reserved: keys can carry it, but no endpoint
        needs it yet.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.