# Update metadata 

Create, update, or remove metadata values for specified key for given incident, monitor, or other resources.

[endpoint]
base_url = "https://uptime.betterstack.com"
path = "/api/v3/metadata"
method = "POST"

[[body_param]]
name = "owner_id"
description = "Resource to update metadata for"
required = true
type = "string"

[[body_param]]
name = "owner_type"
description = "Type of resource to update metadata for. Accepted values: `Monitor`, `Heartbeat`, `Incident`, `WebhookIntegration`, `EmailIntegration`, `IncomingWebhook`, or `CallRouting`"
required = true
type = "string"

[[body_param]]
name = "key"
description = "Metadata key"
required = true
type = "string"

[[body_param]]
name = "values"
description = "Array of metadata values. Existing values for the given key will be replaced. See the [list of metadata API parameters](https://betterstack.com/docs/uptime/api/metadata-api-response-params/) for details."
required = true
type = "array"

[[body_param]]
name = "mode"
description = "How to apply the provided values. Accepted values: `replace` (default) replaces all existing values for the given key, `merge` adds the provided values to the existing ones."
required = false
type = "string"

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

[[header]]
name = "Content_Type"
description = "application/json"
required = false
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''The metadata was successfully created'''
body = '''{
  "data": {
    "id": "25",
    "type": "metadata",
    "attributes": {
      "key": "Key 1",
      "values": [{ "type": "String", "value": "Value 1" }, { "type": "String", "value": "Value 2" }]
      "owner_id": "2",
      "owner_type": "Monitor"
    }
  }
}'''

[[response]]
status = 403
description = '''Authentication failed'''
body = ''''''
[/responses]

#### Example cURL

[code-tabs]
```shell
[label Example]
curl --request POST \
  --url https://uptime.betterstack.com/api/v3/metadata \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "Key 1",
    "values": [
      { "value": "Value 1" },
      { "value": "Value 2" }
    ],
    "owner_id": "2",
    "owner_type": "Monitor"
  }'
```
```shell
[label Typed values]
curl --request POST \
  --url https://uptime.betterstack.com/api/v3/metadata \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "Key 1",
    "values": [
      { "type": "User", "item_id": "17" },
      { "type": "User", "email": "alice@betterstack.com" }
    ],
    "owner_id": "2",
    "owner_type": "Monitor"
  }'
```
```shell
[label Merge values]
curl --request POST \
  --url https://uptime.betterstack.com/api/v3/metadata \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "Key 1",
    "values": [
      { "value": "Value 3" }
    ],
    "mode": "merge",
    "owner_id": "2",
    "owner_type": "Monitor"
  }'
```
```shell
[label Remove metadata]
curl --request POST \
  --url https://uptime.betterstack.com/api/v3/metadata \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "Key 1",
    "values": [],
    "owner_id": "2",
    "owner_type": "Monitor"
  }'
```
[/code-tabs]

[info]
#### Looking for the details of a specific parameter?
Explore [the list of all metadata API parameters](https://betterstack.com/docs/uptime/api/metadata-api-response-params/)
[/info]