Batch upsert catalog records

Creates or updates multiple Catalog records at once, so you can send the same records again without creating duplicates.

Each record you send is matched to an existing record by its primary attribute values, then:

If it matches an existing record, that record is updated. Only the attributes you include change: attributes you leave out keep their values, and an attribute sent with an empty values array is cleared.
If it matches nothing, a new record is created. Existing records that no sent record matches are left unchanged.

When matching, the order of the primary values doesn't matter, and a primary attribute left empty matches only records where it's also empty. If any record in the batch can't be saved, none of them are saved.

PATCH https://incidents.betterstack.com/api/v2/catalog/relations/{relation_id}/records/batch

URL parameters

relation_id

required string

The ID of the Catalog relation you want to create or update records for.

Headers

Authorization

required string

Bearer $TOKEN

Content-Type

required string

application/json

Body parameters

[]

required array

Array of records to create or update. Each record follows the format for creating a single Catalog record.

200

Returns the records in the order you sent them. meta.created lists the IDs of the new records, and meta.updated the IDs of the existing records the batch matched.

Response body

{
  "data": [
    {
      "id": "67",
      "type": "catalog_record",
      "attributes": {
        "attributes": [
          {
            "attribute": {
              "id": 56,
              "name": "Team"
            },
            "values": [
              {
                "type": "String",
                "value": "My Team"
              }
            ]
          },
          {
            "attribute": {
              "id": 57,
              "name": "Team Lead"
            },
            "values": [
              {
                "type": "User",
                "item_id": 123,
                "name": "Alice Smith",
                "email": "alice@example.com"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "68",
      "type": "catalog_record",
      "attributes": {
        "attributes": [
          {
            "attribute": {
              "id": 56,
              "name": "Team"
            },
            "values": [
              {
                "type": "String",
                "value": "Another Team"
              }
            ]
          },
          {
            "attribute": {
              "id": 57,
              "name": "Team Lead"
            },
            "values": [
              {
                "type": "User",
                "item_id": 124,
                "name": "Bob Jones",
                "email": "bob@example.com"
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "created": [
      "68"
    ],
    "updated": [
      "67"
    ]
  }
}

422

A record couldn't be saved, so no records were saved. record_index is that record's position in the array, counting from 0. A record fails when it matches several existing records, has the same primary attribute values as another record in the batch, or doesn't pass validation. Errors in the request itself, like an unknown attribute name, come without record_index.

Response body

{
  "errors": {
    "base": [
      "Record 1: Another row in this batch (index 0) has the same primary values."
    ]
  },
  "record_index": 1
}

Example cURL

Example

Copied!

curl -X "PATCH" "https://incidents.betterstack.com/api/v2/catalog/relations/37/records/batch" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'[
  {
    "attributes": [
      {
        "attribute": { "id": "56", "name": "Team" },
        "values": [
          { "type": "String", "value": "My Team" }
        ]
      },
      {
        "attribute": { "id": "57", "name": "Team Lead" },
        "values": [
          { "type": "User", "email": "alice@example.com" }
        ]
      }
    ]
  },
  {
    "attributes": [
      {
        "attribute": { "id": "56", "name": "Team" },
        "values": [
          { "type": "String", "value": "Another Team" }
        ]
      },
      {
        "attribute": { "id": "57", "name": "Team Lead" },
        "values": [
          { "type": "User", "email": "bob@example.com" }
        ]
      }
    ]
  }
]'

Looking for the details of a specific parameter?

Explore the list of all Catalog record API parameters.

Batch update catalog records

Batch remove catalog records

Explore documentation

Batch upsert catalog records

Example cURL

Looking for the details of a specific parameter?

Please accept cookies