---
title: "tag_links"
method: POST
path: "/v1/watches/bulk-labels"
---

# tag_links

`POST /v1/watches/bulk-labels`

## Request

- Base URL: `https://app.agentlinkops.com`
- URL: `https://app.agentlinkops.com/v1/watches/bulk-labels`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

The JSON body uses the shared tag_links input for up to 100 monitored links. Tags stay separate from the team category and page assessment. Supplied type creates a team choice; type=null deliberately clears it. The change starts no verification or classification job and preserves monitoring status and cadence.

## Headers

- `X-Workspace-ID` string

## Request body

- object
  - `watchIds` string[], required: watch ids; see schema.
  - `addTagIds` string[]: add tag ids; see schema.
  - `removeTagIds` string[]: remove tag ids; see schema.
  - `type` 'contextual_citation' | 'guest_post' | 'recommendation' | 'resource_entry' | 'technical_reference' | 'directory_entry' | 'profile_website' | 'author_attribution' | 'discussion_contribution' | 'navigation_template' | 'badge_embed_attribution' | 'partner_sponsor' | 'other', nullable: type; see schema.

## Response `200`

The JSON body uses the shared tag_links input for up to 100 monitored links. Tags stay separate from the team category and page assessment. Supplied type creates a team choice; type=null deliberately clears it. The change starts no verification or classification job and preserves monitoring status and cadence.

- object
  - `updated` integer, required
  - `items` object[], required: Records in this bounded page.
    - `category_contract` 'link-category-v1': Version of the shared table, API and export category projection.
    - `chosen_category` object: The saved choice and recorded account attribution. Cleared keeps the type empty; automatic permits eligible existing page evidence to supply the displayed category. Neither action reviews or starts AI work.
      - `intent` 'chosen' | 'cleared' | 'automatic', required
      - `id` 'contextual_citation' | 'guest_post' | 'recommendation' | 'resource_entry' | 'technical_reference' | 'directory_entry' | 'profile_website' | 'author_attribution' | 'discussion_contribution' | 'navigation_template' | 'badge_embed_attribution' | 'partner_sponsor' | 'other', nullable, required: Resource identifier returned by the operation.
      - `name` string, nullable, required
      - `standard_name` string, nullable, required
      - `actor_id` string, nullable, required
      - `recorded_at` string, nullable, required
      - `revision` integer, required: Saved label revision; pass as revision to set_link_type. Required for intent=automatic.
      - `deliberate_clear` boolean, required
    - `page_assessment` object: What retained page evidence says about link occurrences. Applicability separates current, previous, expired and unavailable evidence. Suggested is provisional; accepted_manual requires a recorded review; accepted_auto requires a qualified saved policy.
      - `status` 'ready' | 'unavailable', required: Resource lifecycle status.
      - `reason` string, required: Recorded explanation; null when no explanation applies.
      - `read_reason` string, nullable, required
      - `explanation` string, required
      - `applicability` string, required
      - `binding` object, nullable, required
        - `workspaceId` string, required
        - `projectId` string, required
        - `watchId` string, required
      - `capture` object, nullable, required
        - `id` string, required: Resource identifier returned by the operation.
        - `manifest_id` string, nullable, required
        - `observation_id` string, nullable, required
        - `observed_at` string, nullable, required: UTC timestamp of the observation used here.
        - `expires_at` string, nullable, required
      - `source` object, nullable, required
        - `state` string, nullable, required: Saved lifecycle or evidence state, as enumerated for this record.
        - `observed_at` string, nullable, required: UTC timestamp of the observation used here.
        - `observation_id` string, nullable, required
        - `pageUnavailable` boolean, required
      - `assessed_at` string, nullable, required
      - `revision` integer, nullable, required: Highest retained eligible occurrence decision or review revision, or null. Evidence provenance, not a write token.
      - `model_revisions` object[], required
        - `model` string, required
        - `revision` string, nullable, required: Recorded model version or revision, or null. Evidence provenance, not a write token.
      - `policy_revisions` object[], required
        - `taxonomy_version` string, nullable, required
        - `rubric_version` string, nullable, required
        - `policy_revision` union, required: Recorded policy revision as a string or number, or null. Evidence provenance, not a write token.
          - string
          - number
      - `roles` object[], required
        - `id` 'contextual_citation' | 'guest_post' | 'recommendation' | 'resource_entry' | 'technical_reference' | 'directory_entry' | 'profile_website' | 'author_attribution' | 'discussion_contribution' | 'navigation_template' | 'badge_embed_attribution' | 'partner_sponsor' | 'other', required: Resource identifier returned by the operation.
        - `name` string, required
        - `standard_name` string, required
        - `count` integer, required
        - `states` object, required
          - `suggested` integer, required
          - `accepted_manual` integer, required
          - `accepted_auto` integer, required
      - `decision_state` 'suggested' | 'accepted_manual' | 'accepted_auto' | 'mixed' | 'none', required
      - `mixed` boolean, required
      - `coverage` object, required: Occurrence counts for this watch. Null means unavailable. Assessed counts completed evaluations, including inconclusive ones. Classified counts occurrences with a determined role; partial describes type coverage. Retained includes excluded occurrences. Counts do not represent separate watched links.
        - `assessed` integer, nullable, required
        - `classified` integer, nullable, required
        - `eligible` integer, nullable, required
        - `retained` integer, nullable, required
        - `excluded` integer, nullable, required
        - `unassessed` integer, nullable, required
        - `unclassified` integer, nullable, required
        - `partial` boolean, nullable, required
      - `pending_count` integer, nullable, required
      - `failed_count` integer, nullable, required
      - `job_count` integer, nullable, required
      - `review_required_count` integer, nullable, required
    - `display_category` object: The category shown in the everyday table. A deliberate saved choice takes precedence. Otherwise page evidence supplies a category or Mixed types, with its evidence state. Read the reason when no category is available.
      - `source` 'chosen' | 'page_assessment' | 'none', required
      - `kind` 'category' | 'mixed' | 'cleared' | 'unknown', required
      - `id` 'contextual_citation' | 'guest_post' | 'recommendation' | 'resource_entry' | 'technical_reference' | 'directory_entry' | 'profile_website' | 'author_attribution' | 'discussion_contribution' | 'navigation_template' | 'badge_embed_attribution' | 'partner_sponsor' | 'other', nullable, required: Resource identifier returned by the operation.
      - `name` string, required
      - `state` string, required: Saved lifecycle or evidence state, as enumerated for this record.
      - `reason` string, required: Recorded explanation; null when no explanation applies.
      - `applicability` string, required
      - `coverage` object, required: Occurrence counts for this watch. Null means unavailable. Assessed counts completed evaluations, including inconclusive ones. Classified counts occurrences with a determined role; partial describes type coverage. Retained includes excluded occurrences. Counts do not represent separate watched links.
        - `assessed` integer, nullable, required
        - `classified` integer, nullable, required
        - `eligible` integer, nullable, required
        - `retained` integer, nullable, required
        - `excluded` integer, nullable, required
        - `unassessed` integer, nullable, required
        - `unclassified` integer, nullable, required
        - `partial` boolean, nullable, required
    - `id` string, required: Resource identifier returned by the operation.
    - `type` string, nullable, required
    - `type_source` 'model' | 'person', nullable, required
    - `tags` object[], required
      - `id` string, required: Resource identifier returned by the operation.
      - `name` string, required
      - `color` string, required
    - `disavow` 'active' | 'proposed', nullable, required

## Other responses

- `429`: Request-rate or usage refusal. Inspect error.code and recovery details before retrying.
- `default`: Error envelope. Non-configuration 5xx messages are masked and details omitted; allowlisted configuration errors retain static operator recovery.

---

[API](https://skmtc.dev/agentlinkops/apis/agentlinkops-http-api.md) · [All operations](https://skmtc.dev/agentlinkops/apis/agentlinkops-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentlinkops/apis/agentlinkops-http-api/revisions/2a712a1dcfa7?raw)