# Update incident

Update an incident's metadata, the only attribute an incident lets you change.

Older versions of this endpoint return numeric team IDs instead of `t123`.

[endpoint]
base_url = "https://incidents.betterstack.com"
path = "/api/v4/incidents/{incident_id}"
method = "PATCH"

[[path_param]]
name = "incident_id"
description = "The ID of the incident you want to update."
required = true
type = "string"

[[body_param]]
name = "metadata"
description = "An object with metadata keys as the object keys and either a single metadata value or an array of metadata values as the object values. Each value is a plain string or an object with a `type` and the fields that identify the item, as described for `values` when [creating a metadata record](https://betterstack.com/docs/uptime/api/update-an-existing-metadata-record/). All values under one key must be of the same type and must not repeat. The object replaces all of the incident's metadata, including keys Better Stack added like `Origin`, and `{}` removes it all."
required = true
type = "object"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''Returns the updated incident. When the metadata changed, the incident's timeline shows the change.'''
body = '''{
  "data": {
    "id": "25",
    "type": "incident",
    "attributes": {
      "name": "uptime homepage",
      "url": "https://uptime.betterstack.com/",
      "http_method": "get",
      "cause": "Status 404",
      "incident_group_id": null,
      "started_at": "2020-03-09T17:37:56.662Z",
      "acknowledged_at": null,
      "acknowledged_by": null,
      "resolved_at": null,
      "resolved_by": null,
      "status": "Started",
      "team_name": "Testing team",
      "response_content": "\n404 Not Found\n\nNot Found\nThe requested URL /fail was not found on this server.\n",
      "response_options": "{}",
      "regions": ["us", "eu", "as", "au"],
      "response_url": null,
      "screenshot_url": null,
      "origin_url": null,
      "escalation_policy_id": null,
      "call": true,
      "sms": true,
      "email": true,
      "push": true,
      "critical_alert": false,
      "slack_channels": [
        "inc-20-03-09-uptime-homepage-not-found"
      ],
      "metadata": {
        "Owner": [{ "type": "Team", "item_id": "t12345", "name": "Platform team" }],
        "Severity": [{ "type": "String", "value": "high" }]
      }
    },
    "relationships": {
      "monitor": {
        "data": {
          "id": "2",
          "type": "monitor"
        }
      }
    }
  },
  "included": [
    {
      "id": "2",
      "type": "monitor",
      "attributes": {
        "url": "https://uptime.betterstack.com/",
        "pronounceable_name": "Uptime homepage",
        "auth_username": "",
        "auth_password": "",
        "monitor_type": "status",
        "monitor_group_id": null,
        "last_checked_at": "2024-05-29T15:53:40.000Z",
        "status": "paused",
        "policy_id": null,
        "required_keyword": null,
        "verify_ssl": true,
        "check_frequency": 30,
        "call": false,
        "sms": false,
        "email": true,
        "push": true,
        "team_wait": 180,
        "http_method": "get",
        "request_timeout": 30,
        "recovery_period": 180,
        "request_headers": [],
        "request_body": "",
        "follow_redirects": true,
        "remember_cookies": true,
        "created_at": "2020-02-28T19:30:09.956Z",
        "updated_at": "2020-11-23T09:08:20.817Z",
        "ssl_expiration": 14,
        "domain_expiration": null,
        "regions": ["us", "eu", "as", "au"],
        "expected_status_codes": [],
        "port": null,
        "confirmation_period": 0,
        "paused_at": null,
        "paused": false,
        "maintenance_from": null,
        "maintenance_to": null,
        "maintenance_timezone": "Tokyo",
        "maintenance_days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
        "playwright_script": "import { test, expect } from '@playwright/test';\r\n\r\ntest('has title', async ({ page }) => {\r\n  await page.goto('https://betterstack.com/')\r\n  await expect(page).toHaveTitle(/Better Stack/)\r\n});\r\n",
        "checks_version": "v2",
        "ip_version": null
      },
      "relationships": {
        "policy": {
          "data": null
        }
      }
    }
  ]
}'''

[[response]]
status = 403
description = '''Returned when another team escalated the incident to yours. Only the team that owns the incident can update it.'''
body = '''{
  "errors": "You can't update this incident because it was shared with your team."
}'''

[[response]]
status = 422
description = '''Returned when `metadata` is missing or invalid, or the body has any other attribute.'''
body = '''{
  "errors": "Sorry, you misspelled some attributes",
  "invalid_attributes": ["cause"]
}'''
[/responses]

#### Example cURL

```shell
[label Example]
curl --request PATCH \
  --url https://incidents.betterstack.com/api/v4/incidents/123456 \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "metadata": {
      "Severity": "high",
      "Owner": [{ "type": "Team", "name": "Platform team" }]
    }
  }'
```
