Explore documentation
  1. Welcome to Incidents 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Tag on-call in Slack
    4. Mobile apps ↗
    5. Connecting external calendars
    6. Advanced guide
  4. Incident management
    1. Get started
    2. AI SRE investigations
    3. Post mortems
    4. Metadata & Catalog
    5. Screening alerts
    6. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Incidents API
    1. Getting an API token
    2. Pagination
    3. Monitors
    4. Heartbeats
    5. On-call & incidents
    6. Status pages
    7. Metadata
      1. Metadata API
        1. List metadata GET
        2. Update metadata POST
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

Update metadata

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

POST https://incidents.betterstack.com/api/v3/metadata

Headers

Authorization
required string

Bearer $TOKEN

Content-Type
string

application/json

Body parameters

owner_id
required string

Resource to update metadata for

owner_type
required string

Type of resource to update metadata for. Accepted values: Monitor, Heartbeat, Incident, WebhookIntegration, EmailIntegration, IncomingWebhook, or AmazonSnsIntegration

key
required string

Metadata key

values
required array

Array of metadata values. Each value is a plain string or an object described below. All values under one key must be of the same type. Existing values for the given key will be replaced unless mode is merge. Send an empty array to remove the key.

values.0.type
string

Type of the value. Valid options: String, User, Team, Policy, Schedule, Endpoint, Source, SlackIntegration, LinearIntegration, JiraIntegration, MicrosoftTeamsWebhook, ZapierWebhook, NativeWebhook, or PagerDutyWebhook. Endpoint references a monitor and Schedule an on-call calendar. Defaults to String when only value is sent.

values.0.value
string

The text of the value. Required when type is String.

values.0.item_id
string

ID of the referenced item when type is not String. Send item_id, name or email to identify the item.

values.0.name
string

Name of the referenced item, as an alternative to item_id. Endpoint, SlackIntegration, and ZapierWebhook items are referenced by item_id only, and users by item_id or email.

values.0.email
string

E-mail of the referenced user when type is User, as an alternative to item_id.

mode
string

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.

201

The metadata was successfully created

Response 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"
    }
  }
}
200

Values replaced or merged on a key that already had values

Response body

{
  "data": {
    "id": "25",
    "type": "metadata",
    "attributes": {
      "key": "Key 1",
      "values": [
        {
          "type": "String",
          "value": "Value 3"
        }
      ],
      "team_name": "Testing",
      "owner_id": "2",
      "owner_type": "Monitor"
    }
  }
}
204

All values removed when values is empty

403

Authentication failed

Example cURL

Example Typed values Merge values Remove metadata 
curl --request POST \
  --url https://incidents.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"
  }'
curl --request POST \
  --url https://incidents.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"
  }'
curl --request POST \
  --url https://incidents.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"
  }'
curl --request POST \
  --url https://incidents.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"
  }'


Previous article

List metadata

Next article

List New Relic integrations