Update tracker

PATCH /v1/trackers/{id}

Partial update: send only the fields to change. The tracked entity itself (entity_name/entity_type) is immutable; delete and recreate to watch a different entity. Delivery is the monitor's: change it with PATCH /v1/monitors/{id}.

Parameters

Name	Location	Description
id (required)	path	Tracker id, trk_ form.
Idempotency-Key	header	One key per intent, 1 to 255 printable ASCII characters (0x21 to 0x7E); anything else is 400 invalid_idempotency_key. Keys are scoped to the account, credential and resource family. The same key and normalized method, path and body returns the committed response with Idempotency-Replayed: true. A changed intent within the same family returns 409 idempotency_conflict. Monitor and tracker families have independent namespaces. Secret recovery is limited as described by the operation.

Request body

{
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "display_name": {
            "type": "string",
            "description": "Optional label shown in alerts and the dashboard."
          },
          "notify_email": {
            "type": "boolean",
            "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or true is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
            "deprecated": true
          },
          "notify_webhook": {
            "type": "boolean",
            "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or false is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
            "deprecated": true
          },
          "notify_slack": {
            "type": "boolean",
            "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or false is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
            "deprecated": true
          },
          "webhook_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or null is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
            "deprecated": true
          },
          "slack_channel_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or null is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
            "deprecated": true
          },
          "slack_integration_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or null is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
            "deprecated": true
          },
          "person_match_mode": {
            "type": "string",
            "enum": [
              "mentions",
              "appearances",
              "both"
            ],
            "description": "Person trackers only. Mentions (default) matches others talking about the person; appearances matches the person present as a speaker, host or guest; both accepts either. Non-person trackers reject this field. PATCH changes future and pending delivery eligibility, without backfill."
          },
          "filters": {
            "type": "object",
            "additionalProperties": {},
            "description": "Stored filter object. personMatchMode is also accepted here for person trackers. Other filter keys are retained; do not assume they change matching."
          },
          "paused": {
            "type": "boolean",
            "description": "Pause or resume the tracker. Paused trackers stop producing alerts; there is no backfill for the paused window."
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Responses

200 Success

{
  "description": "Success",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    },
    "RateLimit-Limit": {
      "$ref": "#/components/headers/RateLimit-Limit"
    },
    "RateLimit-Remaining": {
      "$ref": "#/components/headers/RateLimit-Remaining"
    },
    "RateLimit-Reset": {
      "$ref": "#/components/headers/RateLimit-Reset"
    },
    "Idempotency-Replayed": {
      "$ref": "#/components/headers/Idempotency-Replayed"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TrackerMutationResponse"
      }
    }
  }
}

400 InvalidRequest

{
  "$ref": "#/components/responses/InvalidRequest"
}

401 AuthenticationError

{
  "$ref": "#/components/responses/AuthenticationError"
}

403 PermissionError

{
  "$ref": "#/components/responses/PermissionError"
}

404 NotFound

{
  "$ref": "#/components/responses/NotFound"
}

409 Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent.

{
  "description": "Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent.",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

429 RateLimited

{
  "$ref": "#/components/responses/RateLimited"
}

500 ServerError

{
  "$ref": "#/components/responses/ServerError"
}

Operation definition

{
  "tags": [
    "Trackers"
  ],
  "operationId": "update_tracker",
  "summary": "Update tracker",
  "description": "Partial update: send only the fields to change. The tracked entity itself (entity_name/entity_type) is immutable; delete and recreate to watch a different entity. Delivery is the monitor's: change it with PATCH /v1/monitors/{id}.",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "description": "Tracker id, trk_ form."
      },
      "required": true,
      "description": "Tracker id, trk_ form.",
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "Idempotency-Key",
      "in": "header",
      "example": "8b2f6c3e-4d1a-4e7b-9c05-2f6a1b7d3e90",
      "description": "One key per intent, 1 to 255 printable ASCII characters (0x21 to 0x7E); anything else is 400 invalid_idempotency_key. Keys are scoped to the account, credential and resource family. The same key and normalized method, path and body returns the committed response with Idempotency-Replayed: true. A changed intent within the same family returns 409 idempotency_conflict. Monitor and tracker families have independent namespaces. Secret recovery is limited as described by the operation."
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "display_name": {
              "type": "string",
              "description": "Optional label shown in alerts and the dashboard."
            },
            "notify_email": {
              "type": "boolean",
              "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or true is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
              "deprecated": true
            },
            "notify_webhook": {
              "type": "boolean",
              "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or false is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
              "deprecated": true
            },
            "notify_slack": {
              "type": "boolean",
              "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or false is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
              "deprecated": true
            },
            "webhook_url": {
              "type": [
                "string",
                "null"
              ],
              "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or null is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
              "deprecated": true
            },
            "slack_channel_id": {
              "type": [
                "string",
                "null"
              ],
              "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or null is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
              "deprecated": true
            },
            "slack_integration_id": {
              "type": [
                "string",
                "null"
              ],
              "description": "Retired: a tracker alerts through its monitor's delivery (set it with PATCH /v1/monitors/{id}). Omitted or null is accepted and ignored; any other value answers 400 tracker_delivery_retired.",
              "deprecated": true
            },
            "person_match_mode": {
              "type": "string",
              "enum": [
                "mentions",
                "appearances",
                "both"
              ],
              "description": "Person trackers only. Mentions (default) matches others talking about the person; appearances matches the person present as a speaker, host or guest; both accepts either. Non-person trackers reject this field. PATCH changes future and pending delivery eligibility, without backfill."
            },
            "filters": {
              "type": "object",
              "additionalProperties": {},
              "description": "Stored filter object. personMatchMode is also accepted here for person trackers. Other filter keys are retained; do not assume they change matching."
            },
            "paused": {
              "type": "boolean",
              "description": "Pause or resume the tracker. Paused trackers stop producing alerts; there is no backfill for the paused window."
            }
          },
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        },
        "RateLimit-Limit": {
          "$ref": "#/components/headers/RateLimit-Limit"
        },
        "RateLimit-Remaining": {
          "$ref": "#/components/headers/RateLimit-Remaining"
        },
        "RateLimit-Reset": {
          "$ref": "#/components/headers/RateLimit-Reset"
        },
        "Idempotency-Replayed": {
          "$ref": "#/components/headers/Idempotency-Replayed"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TrackerMutationResponse"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/InvalidRequest"
    },
    "401": {
      "$ref": "#/components/responses/AuthenticationError"
    },
    "403": {
      "$ref": "#/components/responses/PermissionError"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent.",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/ServerError"
    }
  }
}