Follow entities in a monitor by id or exact name
POST /v1/monitors/{id}/entities
Follows each entity ({ entity_ids: ["ent_..."] }) and each exact name ({ names: [{ name, type }] }) in the monitor: the monitor account's existing tracker for the entity or name (compared case-insensitively) is reused, else a tracker is created in the monitor's account for the canonical entity (a merged id follows its redirect) or the name as given, then the trackers are attached, all in one write. Use names for something not yet indexed; a channel is named by its YouTube channel id, and a channel name answers 400 id_required. Attached trackers use the monitor's delivery settings. Supply 1 to 90 ids and names together; duplicates count once. Each gets one result, ids first then names, in request order; a names result carries name and type in place of entity_id. An id that cannot be followed comes back with attached: false and a reason (entity_not_found, entity_type_not_trackable, tracker_limit_reached, tracked_in_another_monitor) while the rest still attach; a tracker already in another monitor is left there and named in current_monitor_id. Requires the monitors:write and trackers:write scopes.
Parameters
| Name | Location | Description |
|---|
| id (required) | path | Monitor id. |
| 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": {
"entity_ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^ent_[1-9][0-9]*$"
},
"description": "Entity ids (\"ent_...\") to follow in this monitor, from GET /v1/entities/resolve or search. Duplicates count once. A merged id follows its redirect to the canonical entity."
},
"names": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "The exact name to watch, matched case-insensitively against analyzed media, so it can be followed before the entity is indexed. For a channel, the YouTube channel id (UC plus 22 characters); a channel name answers 400 id_required naming GET /v1/entities/resolve?q=...&type=channel."
},
"type": {
"type": "string",
"enum": [
"person",
"organization",
"org",
"product",
"topic",
"channel"
],
"description": "person, organization (org is accepted), product, topic or channel."
},
"person_match_mode": {
"type": "string",
"enum": [
"mentions",
"appearances",
"both"
],
"description": "For a person tracker this request creates; defaults to the top-level person_match_mode. Other types ignore it."
}
},
"required": [
"name",
"type"
],
"additionalProperties": false
},
"description": "Exact names to follow in this monitor, for a name not yet indexed or one you have no id for. The tracker is created in the monitor's account and attached in the same call; the account's tracker for the same name (compared case-insensitively) and type is reused. Duplicates count once."
},
"person_match_mode": {
"type": "string",
"enum": [
"mentions",
"appearances",
"both"
],
"description": "For person trackers this request creates: mentions (default) matches others talking about the person; appearances matches the person present as a speaker, host or guest; both accepts either. Other types ignore it, and a tracker that already exists keeps its own setting (change it with PATCH /v1/trackers/{id})."
}
},
"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/MonitorAddEntitiesResponse"
}
}
}
}
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": [
"Monitors"
],
"operationId": "add_monitor_entities",
"summary": "Follow entities in a monitor by id or exact name",
"description": "Follows each entity ({ entity_ids: [\"ent_...\"] }) and each exact name ({ names: [{ name, type }] }) in the monitor: the monitor account's existing tracker for the entity or name (compared case-insensitively) is reused, else a tracker is created in the monitor's account for the canonical entity (a merged id follows its redirect) or the name as given, then the trackers are attached, all in one write. Use names for something not yet indexed; a channel is named by its YouTube channel id, and a channel name answers 400 id_required. Attached trackers use the monitor's delivery settings. Supply 1 to 90 ids and names together; duplicates count once. Each gets one result, ids first then names, in request order; a names result carries name and type in place of entity_id. An id that cannot be followed comes back with attached: false and a reason (entity_not_found, entity_type_not_trackable, tracker_limit_reached, tracked_in_another_monitor) while the rest still attach; a tracker already in another monitor is left there and named in current_monitor_id. Requires the monitors:write and trackers:write scopes.",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string",
"description": "Monitor id."
},
"required": true,
"description": "Monitor id.",
"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": {
"entity_ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^ent_[1-9][0-9]*$"
},
"description": "Entity ids (\"ent_...\") to follow in this monitor, from GET /v1/entities/resolve or search. Duplicates count once. A merged id follows its redirect to the canonical entity."
},
"names": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "The exact name to watch, matched case-insensitively against analyzed media, so it can be followed before the entity is indexed. For a channel, the YouTube channel id (UC plus 22 characters); a channel name answers 400 id_required naming GET /v1/entities/resolve?q=...&type=channel."
},
"type": {
"type": "string",
"enum": [
"person",
"organization",
"org",
"product",
"topic",
"channel"
],
"description": "person, organization (org is accepted), product, topic or channel."
},
"person_match_mode": {
"type": "string",
"enum": [
"mentions",
"appearances",
"both"
],
"description": "For a person tracker this request creates; defaults to the top-level person_match_mode. Other types ignore it."
}
},
"required": [
"name",
"type"
],
"additionalProperties": false
},
"description": "Exact names to follow in this monitor, for a name not yet indexed or one you have no id for. The tracker is created in the monitor's account and attached in the same call; the account's tracker for the same name (compared case-insensitively) and type is reused. Duplicates count once."
},
"person_match_mode": {
"type": "string",
"enum": [
"mentions",
"appearances",
"both"
],
"description": "For person trackers this request creates: mentions (default) matches others talking about the person; appearances matches the person present as a speaker, host or guest; both accepts either. Other types ignore it, and a tracker that already exists keeps its own setting (change it with PATCH /v1/trackers/{id})."
}
},
"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/MonitorAddEntitiesResponse"
}
}
}
},
"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"
}
}
}