> ## 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.
Available in the deployed MCP and HTTP bundle. Confirm access and inputs with your connected catalog. Workspace scopes and enabled providers still apply.
| 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.
```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}
agentlinkops call monitor_discovery_candidate --args '{"jobId":"job_example","idempotencyKey":"docs-request-001"}'
```
```bash HTTP theme={null}
curl "$AGENTLINKOPS_API_URL/v1/commands/monitor_discovery_candidate" \
-H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"jobId":"job_example","idempotencyKey":"docs-request-001"}'
```
## 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 |
| `deal` | object | Optional | The deal value; allowed values and bounds are specified in this schema. additional fields rejected |
| `deal.costMinor` | integer / null | Optional | |
| `deal.currency` | string / null | Optional | |
| `deal.acquiredOn` | string,null | Optional | |
| `deal.expiresOn` | string,null | Optional | |
| `deal.renewalWindowDays` | integer / null | Optional | |
| `deal.contactRef` | string / null | Optional | |
| `deal.contactLabel` | string / null | Optional | |
| `deal.dealNote` | string / null | Optional | |
| `dealRevision` | integer | Optional | The deal revision value; allowed values and bounds are specified in this schema. minimum: 0; maximum: 9007199254740991 |
### 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.
* **`lifecycle`** (object, optional): additional fields rejected
* **`schema_version`** (number, required): 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): Identifier returned by the related operation.
* **`watch_id`** (string, required): Identifier returned by the related operation.
* **`run_id`** (string, required): Identifier returned by the related operation.
* **`candidate_id`** (string, required): Identifier returned by the related operation.
* **`observation_id`** (string, required): Identifier returned by the related operation.
* **`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).
* **`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
| Field | Type | Presence | Meaning and constraints |
| -------------------------------------------------------------------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `lifecycle` | object | Optional | additional fields rejected |
| `lifecycle.watchId` | string | Required | Identifier returned by the related operation. minLength: 1; maxLength: 200 |
| `lifecycle.projectId` | string | Required | Identifier returned by the related operation. minLength: 1; maxLength: 200 |
| `lifecycle.revision` | integer | Required | Optimistic concurrency revision; supply it as expectedRevision on the next write. minimum: 0; maximum: 9007199254740991 |
| `lifecycle.deal` | object | Required | additional fields rejected |
| `lifecycle.deal.costMinor` | integer / null | Required | |
| `lifecycle.deal.currency` | string / null | Required | |
| `lifecycle.deal.acquiredOn` | string / null | Required | |
| `lifecycle.deal.expiresOn` | string / null | Required | |
| `lifecycle.deal.renewalWindowDays` | integer / null | Required | |
| `lifecycle.deal.contactRef` | string / null | Required | |
| `lifecycle.deal.contactLabel` | string / null | Required | |
| `lifecycle.deal.dealNote` | string / null | Required | |
| `lifecycle.createdAt` | string / null | Required | |
| `lifecycle.updatedAt` | string / null | Required | |
| `schema_version` | number | Required | 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 | Identifier returned by the related operation. |
| `watch_id` | string | Required | Identifier returned by the related operation. |
| `run_id` | string | Required | Identifier returned by the related operation. |
| `candidate_id` | string | Required | Identifier returned by the related operation. |
| `observation_id` | string | Required | Identifier returned by the related operation. |
| `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.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 | |
| `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 | |
| `watch.observation_state.checked_at` | string | Optional | UTC timestamp of the saved check. |
| `watch.observation_state.lastChangedAt` | string / null | Optional | |
| `watch.observation_state.firstAbsentAt` | string / null | Optional | |
| `watch.observation_state.consecutiveAbsent` | number | Optional | |
| `watch.observation_state.nextCheckAt` | string / null | Optional | |
| `watch.observation_state.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `watch.observation_state.latestAttempt` | object / null | Optional | |
| `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 | |
| `watch.observation_state.latestAttempt.httpStatus` | number / null | Optional | |
| `watch.observation_state.latestAttempt.occurrenceCount` | number | Optional | |
| `watch.observation_state.latestAttempt.occurrences` | array | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].href` | string / null | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].targetUrl` | string / null | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].anchor` | string / null | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].rel` | array | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].context` | string / null | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].locator` | object / null | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].locator.line` | number / null | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].locator.column` | number / null | Optional | |
| `watch.observation_state.latestAttempt.occurrences[].locator.offset` | number / null | Optional | |
| `watch.observation_state.latestAttempt.checkerVersion` | string | Optional | |
| `watch.observation_state.lastSuccessfulObservation` | object / null | Optional | |
| `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 | |
| `watch.observation_state.lastSuccessfulObservation.httpStatus` | number / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrenceCount` | number | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences` | array | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].href` | string / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].targetUrl` | string / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].anchor` | string / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].rel` | array | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].context` | string / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator` | object / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator.line` | number / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator.column` | number / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.occurrences[].locator.offset` | number / null | Optional | |
| `watch.observation_state.lastSuccessfulObservation.checkerVersion` | string | Optional | |
| `watch.observation_state.lastSuccessfulObservationSameAsLatestAttempt` | boolean | Optional | |
| `watch.observation_state.confirmedState` | string / null | Optional | |
| `watch.observation_state.lastSuccessfulAt` | string / null | Optional | |
| `watch.observation_state.lastHealthyAt` | string / null | Optional | |
| `watch.observation_state.firstUnavailableAt` | string / null | Optional | |
| `watch.observation_state.unavailableCount` | number | Optional | |
| `watch.observation_state.wasEverHealthy` | boolean | Optional | |
| `watch.observation_state.retryNotBefore` | string / null | Optional | |
| `watch.observation_state.ignored` | boolean | Optional | |
| `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 | |
| `watch.last_success_at` | string / null | Required | |
| `watch.last_observation_id` | string / null | Required | Identifier returned by the related operation. |
| `watch.next_check_at` | string / null | Required | |
| `watch.overdue_reason` | string / null | Required | |
| `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 | |
| `watch.expected_anchor` | string / null | Required | |
| `watch.expected_rel` | array / null | Required | |
| `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 | Identifier returned by the related operation. |
| `watch.history_compacted_before` | string / null | Optional | |
| `watch.created` | boolean | Optional | True when this request created the record; false when an existing record was reused. |
| `watch.detail` | string | Optional | |
| `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).