> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor discovery candidate

> Explicitly enroll the watch from a completed present candidate verification.

`monitor_discovery_candidate`

Explicitly enroll the watch from a completed present candidate verification. Preserves candidate, run, observation and local-reference provenance. Active-watch limits apply; replay never reactivates a subsequently paused watch. Cadence applies when activating a paused watch.

<Note>Development preview. This command is absent from the hosted MCP readback. Generic CLI/HTTP calls require a matching development server. Configure LINKTRAIL\_API\_URL; production does not expose these command routes.</Note>

| Access                            | Behavior              |
| --------------------------------- | --------------------- |
| `discovery:read`, `watches:write` | Writes or admits work |

Checks and monitoring can consume workspace capacity. Queued admission is not a completed observation; inspect the returned job or saved state.

## Example request

Connect through [MCP](/guides/connect-mcp), [CLI](/guides/connect-cli), or [HTTP](/guides/connect-http). Replace example identifiers with records from your workspace.

<CodeGroup>
  ```json MCP theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "monitor_discovery_candidate",
      "arguments": {
        "jobId": "job_example",
        "idempotencyKey": "docs-request-001"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  linktrail call monitor_discovery_candidate --args '{"jobId":"job_example","idempotencyKey":"docs-request-001"}'
  ```

  ```bash HTTP theme={null}
  curl "$LINKTRAIL_API_URL/v1/commands/monitor_discovery_candidate" \
    -H "Authorization: Bearer $LINKTRAIL_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"jobId":"job_example","idempotencyKey":"docs-request-001"}'
  ```
</CodeGroup>

## Returned result

Illustrative data validated against the documented response schema. IDs and dates are examples, not a live account capture. MCP returns this data in `structuredContent` and in a text content block; generic HTTP and CLI return the JSON result directly.

```json theme={null}
{
  "schema_version": 1,
  "workspace_id": "ws_example",
  "project_id": "pr_example",
  "verification_job_id": "job_example",
  "watch_id": "watch_example",
  "run_id": "dr_example",
  "candidate_id": "dc_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "observation_id": "obs_example",
  "local_reference": "ledger:example",
  "created_at": "2026-09-13T12:00:00.000Z",
  "watch": {
    "workspace_id": "ws_example",
    "project_id": "pr_example",
    "status": "active",
    "cadence_seconds": 86400,
    "state": "present",
    "observation_state": {
      "state": "present"
    },
    "created_at": "2026-09-13T12:00:00.000Z",
    "updated_at": "2026-09-13T12:00:00.000Z",
    "last_attempt_at": "2026-09-13T12:00:00.000Z",
    "last_success_at": "2026-09-13T12:00:00.000Z",
    "last_observation_id": "obs_example",
    "next_check_at": "2026-09-13T12:00:00.000Z",
    "overdue_reason": null,
    "id": "watch_example",
    "source_url": "https://publisher.example.org/article",
    "target_url": "https://example.com/",
    "target_scope": "exact",
    "expected_anchor": null,
    "expected_rel": null,
    "local_reference": "ledger:example",
    "last_successful_observation_id": "obs_example"
  },
  "replayed": false,
  "recurring_monitoring_created": true
}
```

## Input fields

Omit optional fields when you do not want to supply them. Null is accepted only where listed. Unknown input properties are rejected.

| Field            | Type    | Presence | Meaning and constraints                                                                                                                |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `jobId`          | string  | Required | Identifier of the job returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$"                                  |
| `idempotencyKey` | string  | Required | Caller-generated key reused only for retries of the same operation and arguments in this workspace. pattern: "^\[\x21-\x7e]\{1,200}\$" |
| `cadenceSeconds` | integer | Optional | Scheduled check interval in seconds, from 3600 to 2592000. minimum: 3600; maximum: 2592000; default: 86400                             |

### Validation and omitted values

Requires a completed present verification. The requested cadence applies when activating the paused verification watch; replay never reactivates a watch paused after conversion.

### Defaults when omitted

| Field            | Default |
| ---------------- | ------- |
| `cadenceSeconds` | `86400` |

## Output fields

Fields inside optional or nullable parents apply only when that parent exists. [Common schema conventions](/reference/schemas) explain evidence states, empty lists and extensions.

| Field                                                                            | Type          | Presence | Meaning and constraints                                                              |
| -------------------------------------------------------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `schema_version`                                                                 | number        | Required | schema version recorded for this result. must equal 1                                |
| `workspace_id`                                                                   | string        | Required | Workspace that owns this record.                                                     |
| `project_id`                                                                     | string        | Required | Project that owns this record.                                                       |
| `verification_job_id`                                                            | string        | Required | verification job id recorded for this result.                                        |
| `watch_id`                                                                       | string        | Required | watch id recorded for this result.                                                   |
| `run_id`                                                                         | string        | Required | run id recorded for this result.                                                     |
| `candidate_id`                                                                   | string        | Required | candidate id recorded for this result.                                               |
| `observation_id`                                                                 | string        | Required | observation id recorded for this result.                                             |
| `local_reference`                                                                | string / null | Required | Customer reference for joining this record to a local ledger entry.                  |
| `created_at`                                                                     | string        | Required | UTC timestamp when the record was created.                                           |
| `watch`                                                                          | object        | Required | watch recorded for this result.                                                      |
| `watch.id`                                                                       | string        | Required | Resource identifier returned by the operation.                                       |
| `watch.workspace_id`                                                             | string        | Required | Workspace that owns this record.                                                     |
| `watch.project_id`                                                               | string        | Required | Project that owns this record.                                                       |
| `watch.status`                                                                   | string        | Required | Resource lifecycle status. values: "active", "paused"                                |
| `watch.cadence_seconds`                                                          | number        | Required | cadence seconds recorded for this result.                                            |
| `watch.state`                                                                    | string        | Required | Saved lifecycle or evidence state, as enumerated for this record.                    |
| `watch.observation_state`                                                        | object        | Required | Saved observation state. Before the first check, this object can be empty.           |
| `watch.observation_state.state`                                                  | string        | Optional | Saved lifecycle or evidence state, as enumerated for this record.                    |
| `watch.observation_state.uncertain`                                              | boolean       | Optional | uncertain recorded for this result.                                                  |
| `watch.observation_state.checked_at`                                             | string        | Optional | UTC timestamp of the saved check.                                                    |
| `watch.observation_state.lastChangedAt`                                          | string / null | Optional | last Changed At recorded for this result.                                            |
| `watch.observation_state.firstAbsentAt`                                          | string / null | Optional | first Absent At recorded for this result.                                            |
| `watch.observation_state.consecutiveAbsent`                                      | number        | Optional | consecutive Absent recorded for this result.                                         |
| `watch.observation_state.nextCheckAt`                                            | string / null | Optional | next Check At recorded for this result.                                              |
| `watch.observation_state.reason`                                                 | string / null | Optional | Recorded explanation; null when no explanation applies.                              |
| `watch.observation_state.latestAttempt`                                          | object / null | Optional | latest Attempt recorded for this result.                                             |
| `watch.observation_state.latestAttempt.state`                                    | string        | Optional | Saved lifecycle or evidence state, as enumerated for this record.                    |
| `watch.observation_state.latestAttempt.reason`                                   | string / null | Optional | Recorded explanation; null when no explanation applies.                              |
| `watch.observation_state.latestAttempt.checkedAt`                                | string        | Optional | checked At recorded for this result.                                                 |
| `watch.observation_state.latestAttempt.httpStatus`                               | number / null | Optional | http Status recorded for this result.                                                |
| `watch.observation_state.latestAttempt.occurrenceCount`                          | number        | Optional | occurrence Count recorded for this result.                                           |
| `watch.observation_state.latestAttempt.occurrences`                              | array         | Optional | occurrences recorded for this result.                                                |
| `watch.observation_state.latestAttempt.occurrences[].href`                       | string / null | Optional | href recorded for this result.                                                       |
| `watch.observation_state.latestAttempt.occurrences[].targetUrl`                  | string / null | Optional | target Url recorded for this result.                                                 |
| `watch.observation_state.latestAttempt.occurrences[].anchor`                     | string / null | Optional | anchor recorded for this result.                                                     |
| `watch.observation_state.latestAttempt.occurrences[].rel`                        | array         | Optional | rel recorded for this result.                                                        |
| `watch.observation_state.latestAttempt.occurrences[].context`                    | string / null | Optional | context recorded for this result.                                                    |
| `watch.observation_state.latestAttempt.occurrences[].locator`                    | object / null | Optional | locator recorded for this result.                                                    |
| `watch.observation_state.latestAttempt.occurrences[].locator.line`               | number / null | Optional | line recorded for this result.                                                       |
| `watch.observation_state.latestAttempt.occurrences[].locator.column`             | number / null | Optional | column recorded for this result.                                                     |
| `watch.observation_state.latestAttempt.occurrences[].locator.offset`             | number / null | Optional | offset recorded for this result.                                                     |
| `watch.observation_state.latestAttempt.checkerVersion`                           | string        | Optional | checker Version recorded for this result.                                            |
| `watch.observation_state.lastSuccessfulObservation`                              | object / null | Optional | last Successful Observation recorded for this result.                                |
| `watch.observation_state.lastSuccessfulObservation.state`                        | string        | Optional | Saved lifecycle or evidence state, as enumerated for this record.                    |
| `watch.observation_state.lastSuccessfulObservation.reason`                       | string / null | Optional | Recorded explanation; null when no explanation applies.                              |
| `watch.observation_state.lastSuccessfulObservation.checkedAt`                    | string        | Optional | checked At recorded for this result.                                                 |
| `watch.observation_state.lastSuccessfulObservation.httpStatus`                   | number / null | Optional | http Status recorded for this result.                                                |
| `watch.observation_state.lastSuccessfulObservation.occurrenceCount`              | number        | Optional | occurrence Count recorded for this result.                                           |
| `watch.observation_state.lastSuccessfulObservation.occurrences`                  | array         | Optional | occurrences recorded for this result.                                                |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].href`           | string / null | Optional | href recorded for this result.                                                       |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].targetUrl`      | string / null | Optional | target Url recorded for this result.                                                 |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].anchor`         | string / null | Optional | anchor recorded for this result.                                                     |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].rel`            | array         | Optional | rel recorded for this result.                                                        |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].context`        | string / null | Optional | context recorded for this result.                                                    |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator`        | object / null | Optional | locator recorded for this result.                                                    |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator.line`   | number / null | Optional | line recorded for this result.                                                       |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator.column` | number / null | Optional | column recorded for this result.                                                     |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator.offset` | number / null | Optional | offset recorded for this result.                                                     |
| `watch.observation_state.lastSuccessfulObservation.checkerVersion`               | string        | Optional | checker Version recorded for this result.                                            |
| `watch.observation_state.lastSuccessfulObservationSameAsLatestAttempt`           | boolean       | Optional | last Successful Observation Same As Latest Attempt recorded for this result.         |
| `watch.observation_state.confirmedState`                                         | string / null | Optional | confirmed State recorded for this result.                                            |
| `watch.observation_state.lastSuccessfulAt`                                       | string / null | Optional | last Successful At recorded for this result.                                         |
| `watch.observation_state.lastHealthyAt`                                          | string / null | Optional | last Healthy At recorded for this result.                                            |
| `watch.observation_state.firstUnavailableAt`                                     | string / null | Optional | first Unavailable At recorded for this result.                                       |
| `watch.observation_state.unavailableCount`                                       | number        | Optional | unavailable Count recorded for this result.                                          |
| `watch.observation_state.wasEverHealthy`                                         | boolean       | Optional | was Ever Healthy recorded for this result.                                           |
| `watch.observation_state.retryNotBefore`                                         | string / null | Optional | retry Not Before recorded for this result.                                           |
| `watch.observation_state.ignored`                                                | boolean       | Optional | ignored recorded for this result.                                                    |
| `watch.created_at`                                                               | string        | Required | UTC timestamp when the record was created.                                           |
| `watch.updated_at`                                                               | string        | Required | UTC timestamp of the last record update.                                             |
| `watch.last_attempt_at`                                                          | string / null | Required | last attempt at recorded for this result.                                            |
| `watch.last_success_at`                                                          | string / null | Required | last success at recorded for this result.                                            |
| `watch.last_observation_id`                                                      | string / null | Required | last observation id recorded for this result.                                        |
| `watch.next_check_at`                                                            | string / null | Required | next check at recorded for this result.                                              |
| `watch.overdue_reason`                                                           | string / null | Required | overdue reason recorded for this result.                                             |
| `watch.source_url`                                                               | string        | Required | Publisher page URL recorded in this evidence.                                        |
| `watch.target_url`                                                               | string        | Required | Destination URL recorded in this evidence.                                           |
| `watch.target_scope`                                                             | string        | Required | target scope recorded for this result.                                               |
| `watch.expected_anchor`                                                          | string / null | Required | expected anchor recorded for this result.                                            |
| `watch.expected_rel`                                                             | array / null  | Required | expected rel recorded for this result.                                               |
| `watch.local_reference`                                                          | string / null | Required | Customer reference for joining this record to a local ledger entry.                  |
| `watch.last_successful_observation_id`                                           | string / null | Required | last successful observation id recorded for this result.                             |
| `watch.history_compacted_before`                                                 | string / null | Optional | history compacted before recorded for this result.                                   |
| `watch.created`                                                                  | boolean       | Optional | True when this request created the record; false when an existing record was reused. |
| `watch.detail`                                                                   | string        | Optional | detail recorded for this result.                                                     |
| `replayed`                                                                       | boolean       | Required | True when the response reuses an earlier request with the same idempotency value.    |
| `recurring_monitoring_created`                                                   | boolean       | Required | Whether this operation enrolled recurring monitoring. must equal true                |

[Download input schema](/schemas/monitor_discovery_candidate.input.json) · [Download output schema](/schemas/monitor_discovery_candidate.output.json)

## Errors and retries

The command is annotated idempotent. Reuse an accepted idempotency key when the input provides one; changing the payload under a reused key can conflict.

See [error recovery](/reference/errors) for status, scope, cooldown, cursor and retry handling. Unknown observations are result data and do not establish loss.

## HTTP resource routes

These existing resource routes share the operation’s domain behavior. Their parameter placement, status and response envelope can differ from generic invocation. See [HTTP route details](/reference/http/routes).

| Method and route                                   | Success | Details                                                                                                                   |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/discovery/verifications/{jobId}/monitor` | 200     | Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route. |

## Continue

[get\_link\_watch](/reference/commands/get_link_watch)

Follow the [related workflow](/guides/import-and-verify), inspect [capability status](/capability-status), or return to the [command index](/reference/index).