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

# Update Alert

> Update a single alert by its platform alert ID.

Update a single alert, identified by the `platform_alert_id` you sent when you synced it.

**Field behavior**

* Omitted field - the current value is kept
* Field set to `null` - the value is cleared
* Field set to a value - the value is updated

`status` is required on every request.

**Automatic timestamps**

* Setting `assigned_to` without `assigned_at`, or `resolved_by` without `resolved_at`, sets the timestamp to the current time.
* Changing `status` to `under_review` sets `assigned_at` to the current time, unless you send `assigned_at`.
* Changing `status` to `closed` sets `resolved_at` to the current time, unless you send `resolved_at`.
* Changing `status` from `closed` to another status clears `resolved_at` and `resolved_by`, unless you send them.

**Validation**

* Timestamps more than 5 minutes in the future are rejected.
* Timestamps must be in order: `first_observed_at` before `last_observed_at`, and `first_observed_at`, `detected_at`, `assigned_at`, `resolved_at` in that order.

**Authentication** - Requires `X-Api-Key` header


## OpenAPI

````yaml /api-reference/openapi.json patch /v1/alert-sync/{platform_alert_id}
openapi: 3.1.0
info:
  title: Rilevera Customer Alert API
  description: >-
    Programmatically sync alert data from your security platforms into Rilevera
    for comprehensive security monitoring and analysis.


    **Base URL:** `https://api.rilevera.com`
  version: 1.0.0
  contact:
    name: Rilevera Support
    email: support@rilevera.com
servers:
  - url: https://api.rilevera.com
    description: Production API
security:
  - ApiKeyAuth: []
tags:
  - name: Alerts
    description: Alert synchronization endpoints
  - name: Health
    description: Service health monitoring
paths:
  /v1/alert-sync/{platform_alert_id}:
    patch:
      tags:
        - Alerts
      summary: Update Alert
      description: >-
        Update a single alert, identified by the `platform_alert_id` you sent
        when you synced it.


        **Field behavior**

        - Omitted field - the current value is kept

        - Field set to `null` - the value is cleared

        - Field set to a value - the value is updated


        `status` is required on every request.


        **Automatic timestamps**

        - Setting `assigned_to` without `assigned_at`, or `resolved_by` without
        `resolved_at`, sets the timestamp to the current time.

        - Changing `status` to `under_review` sets `assigned_at` to the current
        time, unless you send `assigned_at`.

        - Changing `status` to `closed` sets `resolved_at` to the current time,
        unless you send `resolved_at`.

        - Changing `status` from `closed` to another status clears `resolved_at`
        and `resolved_by`, unless you send them.


        **Validation**

        - Timestamps more than 5 minutes in the future are rejected.

        - Timestamps must be in order: `first_observed_at` before
        `last_observed_at`, and `first_observed_at`, `detected_at`,
        `assigned_at`, `resolved_at` in that order.


        **Authentication** - Requires `X-Api-Key` header
      operationId: patchAlert
      parameters:
        - name: platform_alert_id
          in: path
          required: true
          schema:
            type: string
          description: Unique alert ID from your platform
          example: sumo-alert-12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertPatchRequest'
            example:
              status: closed
              resolution_summary: Confirmed as a scheduled penetration test.
              final_disposition: benign_positive
      responses:
        '200':
          description: Alert updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertPatchResponse'
              example:
                platform_alert_id: sumo-alert-12345
                source_platform: sumologic
                detected_at: '2024-01-15T10:30:00.000Z'
                first_observed_at: '2024-01-15T10:25:00.000Z'
                last_observed_at: '2024-01-15T10:30:00.000Z'
                alert_title: Suspicious Login Activity Detected
                alert_description: Multiple failed login attempts from IP 192.168.1.100
                severity: high
                status: closed
                assigned_to: unknown
                assigned_at: '2024-01-15T14:02:11.000Z'
                resolved_by: unknown
                resolved_at: '2024-01-15T14:02:11.000Z'
                resolution_summary: Confirmed as a scheduled penetration test.
                final_disposition: benign_positive
                tags:
                  - authentication
                  - brute-force
                  - external-ip
                updated_at: '2024-01-15T14:02:11.000Z'
                response_metadata:
                  type: AlertPatchResponse
        '400':
          description: >-
            Bad Request - Invalid alert data, such as timestamps in the future
            or out of order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing, invalid, or expired API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - The API key lacks the required permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - The request body failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '444':
          description: Not Found - No alert exists with this `platform_alert_id`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Update operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AlertPatchRequest:
      type: object
      required:
        - status
      description: >-
        Fields to update. Omit a field to keep its current value. Set a field to
        `null` to clear it.
      properties:
        status:
          type: string
          description: Current status of the alert
          enum:
            - new
            - open
            - under_review
            - closed
        platform_rule_id:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            Rule ID(s) that triggered this alert. Replaces the existing rule
            IDs. Send `[]` to remove all rule IDs; `null` leaves them unchanged.
        source_platform:
          type:
            - string
            - 'null'
          description: Platform where the alert originated
        alert_title:
          type:
            - string
            - 'null'
          description: Human-readable alert title
        alert_description:
          type:
            - string
            - 'null'
          description: Detailed description of the alert
        severity:
          type:
            - string
            - 'null'
          enum:
            - info
            - low
            - medium
            - high
            - critical
            - null
          description: Severity level
        detected_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the rule detected and triggered this alert
        first_observed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: First time the underlying condition was observed
        last_observed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Most recent time the condition was seen
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            Tags associated with the alert. Replaces the existing tags. `null`
            clears all tags.
        assigned_to:
          type:
            - string
            - 'null'
          description: User assigned to investigate the alert
        assigned_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the alert was assigned
        resolved_by:
          type:
            - string
            - 'null'
          description: User who resolved or closed the alert
        resolved_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the alert was resolved
        resolution_summary:
          type:
            - string
            - 'null'
          description: Summary of findings or resolution
        final_disposition:
          type:
            - string
            - 'null'
          description: Final classification of the alert
          enum:
            - closed_without_reason
            - duplicate
            - informational
            - false_positive
            - benign_positive
            - true_positive
            - other
            - null
    AlertPatchResponse:
      type: object
      properties:
        platform_alert_id:
          type: string
          description: Unique alert ID from your platform
        source_platform:
          type: string
          description: Platform where the alert originated
        detected_at:
          type: string
          format: date-time
          description: When the rule detected and triggered this alert
        first_observed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: First time the underlying condition was observed
        last_observed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Most recent time the condition was seen
        alert_title:
          type:
            - string
            - 'null'
          description: Human-readable alert title
        alert_description:
          type:
            - string
            - 'null'
          description: Detailed description of the alert
        severity:
          type:
            - string
            - 'null'
          enum:
            - info
            - low
            - medium
            - high
            - critical
            - null
          description: Severity level
        status:
          type:
            - string
            - 'null'
          enum:
            - new
            - open
            - under_review
            - closed
            - null
          description: Current status of the alert
        assigned_to:
          type:
            - string
            - 'null'
          description: User assigned to investigate the alert
        assigned_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the alert was assigned
        resolved_by:
          type:
            - string
            - 'null'
          description: User who resolved or closed the alert
        resolved_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the alert was resolved
        resolution_summary:
          type:
            - string
            - 'null'
          description: Summary of findings or resolution
        final_disposition:
          type:
            - string
            - 'null'
          description: Final classification of the alert
          enum:
            - closed_without_reason
            - duplicate
            - informational
            - false_positive
            - benign_positive
            - true_positive
            - other
            - null
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the alert
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the alert was last updated
        response_metadata:
          $ref: '#/components/schemas/ResponseMetadata'
    ErrorResponse:
      type: object
      required:
        - userMessage
        - errorType
        - requestId
      properties:
        userMessage:
          type: string
          description: Description of the error
        errorType:
          type: string
          description: Error type identifier
        requestId:
          type:
            - string
            - 'null'
          description: Request ID. Include it when you contact support.
        title:
          type: string
          description: Short error title, when available
        additionalContext:
          type: string
          description: Additional detail about the error, when available
    ValidationErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            validationErrors:
              type: array
              description: Fields that failed validation
              items:
                type: object
                properties:
                  loc:
                    type: array
                    items:
                      type:
                        - string
                        - integer
                    description: Location of the invalid field
                  msg:
                    type: string
                    description: Validation message
                  type:
                    type: string
                    description: Validation error type
    ResponseMetadata:
      type: object
      properties:
        type:
          type: string
          description: Response type identifier
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Your Rilevera API key. Contact your administrator to obtain one.

````

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