> ## 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.
# Verify discovery candidate
> Request an asynchronous check of one saved discovery candidate.
`verify_discovery_candidate`
Request an asynchronous check of one saved discovery candidate. Returns a verification record and queued job with immutable lineage. Requires an idempotency key; consumes check allowance when executed. Does not establish a verified result synchronously.
Hosted MCP registration verified. These schemas describe the development contract; confirm supported inputs with tools/list. Generic CLI/HTTP calls require a matching development server. Configure LINKTRAIL\_API\_URL; production does not expose these command routes.
| 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": "verify_discovery_candidate",
"arguments": {
"runId": "run_example",
"candidateId": "dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"idempotencyKey": "docs-request-001"
}
}
}
```
```bash CLI theme={null}
linktrail call verify_discovery_candidate --args '{"runId":"run_example","candidateId":"dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","idempotencyKey":"docs-request-001"}'
```
```bash HTTP theme={null}
curl "$LINKTRAIL_API_URL/v1/commands/verify_discovery_candidate" \
-H "Authorization: Bearer $LINKTRAIL_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"runId":"run_example","candidateId":"dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","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",
"run_id": "run_example",
"candidate_id": "dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"watch_id": "watch_example",
"job_id": "job_example",
"local_reference": null,
"created_at": "2026-09-13T12:00:00.000Z",
"candidate": {
"v": 1,
"id": "dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"workspace_id": "ws_example",
"project_id": "pr_example",
"discovery_run_id": "run_example",
"source_url": "https://publisher.example.org/article",
"target_url": "https://example.com/",
"provider": "linktrail_corpus",
"data_mode": "owned_corpus",
"provider_retrieved_at": "2026-09-13T12:00:00.000Z",
"provider_first_seen": "2026-09-13T12:00:00.000Z",
"provider_prev_seen": null,
"provider_last_seen": "2026-09-13T12:00:00.000Z",
"provider_status": {
"is_lost": null,
"is_broken": null,
"is_new": null
},
"anchor": "Example",
"rel": [],
"dofollow": true,
"link_type": "anchor",
"source_http_status": 200,
"target_http_status": null,
"links_count": 1,
"provider_metrics": {
"linktrail_corpus": {
"source_outlink_count": 1,
"source_external_outlink_count": 1,
"fetch_kind": "direct",
"extraction_complete": true
}
},
"verification_status": "not_checked",
"verified_at": null,
"observation_id": null
},
"job": {
"id": "job_example",
"state": "queued",
"execution_mode": "candidate_once",
"error_code": null,
"created_at": "2026-09-13T12:00:00.000Z",
"completed_at": null,
"usage": {
"unit": "source_check",
"units": 1,
"state": "reserved",
"period": "2026-09"
}
},
"observation": null,
"watch": {
"id": "watch_example",
"status": "paused",
"local_reference": null
},
"recurring_monitoring_created": false,
"replayed": false
}
```
## 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 |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `runId` | string | Required | Identifier of the run returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `candidateId` | string | Required | Identifier of the candidate returned by its create or list operation. pattern: "^dc\_\[a-f0-9]\{64}\$" |
| `localReference` | string | Optional | Customer-owned reference to associate this record with a local ledger entry. minLength: 1; maxLength: 200 |
| `idempotencyKey` | string | Required | Caller-generated key reused only for retries of the same operation and arguments in this workspace. pattern: "^\[\x21-\x7e]\{1,200}\$" |
### Validation and omitted values
Omitted localReference remains null. The candidate must belong to the supplied saved run. Admission returns a queued job, not verified presence.
## 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. |
| `run_id` | string | Required | run id recorded for this result. |
| `candidate_id` | string | Required | candidate id recorded for this result. |
| `watch_id` | string | Required | watch id recorded for this result. |
| `job_id` | string | Required | job 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. |
| `candidate` | object | Required | candidate recorded for this result. |
| `candidate.v` | number | Required | v recorded for this result. must equal 1 |
| `candidate.id` | string | Required | Resource identifier returned by the operation. pattern: "^dc\_\[a-f0-9]\{64}\$" |
| `candidate.workspace_id` | string | Required | Workspace that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `candidate.project_id` | string | Required | Project that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `candidate.discovery_run_id` | string | Required | discovery run id recorded for this result. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$" |
| `candidate.source_url` | string | Required | Publisher page URL recorded in this evidence. maxLength: 4096 |
| `candidate.target_url` | string | Required | Destination URL recorded in this evidence. maxLength: 4096 |
| `candidate.provider` | string | Required | provider recorded for this result. values: "linktrail\_corpus", "dataforseo", "imported" |
| `candidate.data_mode` | string | Required | data mode recorded for this result. values: "synthetic", "owned\_corpus", "provider\_index", "imported" |
| `candidate.provider_retrieved_at` | string | Required | Timestamp when the upstream evidence was retrieved. format: "date-time"; pattern: "^(?:(?:\d\d\[2468]\[048]\|\d\d\[13579]\[26]\|\d\d0\[48]\|\[02468]\[048]00\|\[13579]\[26]00)-02-29\|\d\{4}-(?:(?:0\[13578]\|1\[02])-(?:0\[1-9]\|\[12]\d\|3\[01])\|(?:0\[469]\|11)-(?:0\[1-9]\|\[12]\d\|30)\|(?:02)-(?:0\[1-9]\|1\d\|2\[0-8])))T(?:(?:\[01]\d\|2\[0-3]):\[0-5]\d:\[0-5]\d\\.\d\{3}(?:Z))\$" |
| `candidate.provider_first_seen` | string / null | Required | provider first seen recorded for this result. |
| `candidate.provider_prev_seen` | string / null | Required | provider prev seen recorded for this result. |
| `candidate.provider_last_seen` | string / null | Required | provider last seen recorded for this result. |
| `candidate.provider_status` | object | Required | provider status recorded for this result. additional fields rejected |
| `candidate.provider_status.is_lost` | boolean / null | Required | is lost recorded for this result. |
| `candidate.provider_status.is_broken` | boolean / null | Required | is broken recorded for this result. |
| `candidate.provider_status.is_new` | boolean / null | Required | is new recorded for this result. |
| `candidate.anchor` | string / null | Required | anchor recorded for this result. |
| `candidate.rel` | array / null | Required | rel recorded for this result. |
| `candidate.dofollow` | boolean / null | Required | dofollow recorded for this result. |
| `candidate.link_type` | string / null | Required | link type recorded for this result. |
| `candidate.source_http_status` | integer / null | Required | source http status recorded for this result. |
| `candidate.target_http_status` | integer / null | Required | target http status recorded for this result. |
| `candidate.links_count` | integer / null | Required | links count recorded for this result. |
| `candidate.provider_metrics` | object / object / object | Required | provider metrics recorded for this result. |
| `candidate.provider_metrics.dataforseo` | object | Required | dataforseo recorded for this result. additional fields rejected |
| `candidate.provider_metrics.dataforseo.rank` | integer / null | Required | rank recorded for this result. |
| `candidate.provider_metrics.dataforseo.page_from_rank` | integer / null | Required | page from rank recorded for this result. |
| `candidate.provider_metrics.dataforseo.domain_from_rank` | integer / null | Required | domain from rank recorded for this result. |
| `candidate.provider_metrics.dataforseo.backlink_spam_score` | integer / null | Required | backlink spam score recorded for this result. |
| `candidate.provider_metrics.dataforseo.rank_scale` | string | Required | rank scale recorded for this result. must equal "one\_thousand" |
| `candidate.provider_metrics.imported` | object | Required | imported recorded for this result. additional fields rejected |
| `candidate.provider_metrics.imported.supplier` | string | Required | supplier recorded for this result. values: "ahrefs", "google\_search\_console", "semrush", "majestic", "moz", "dataforseo", "linkody", "csv" |
| `candidate.provider_metrics.imported.supplier_row_id` | string / null | Required | supplier row id recorded for this result. |
| `candidate.provider_metrics.imported.supplier_generated_at` | string / null | Required | supplier generated at recorded for this result. |
| `candidate.provider_metrics.imported.supplier_metrics` | object / null | Required | supplier metrics recorded for this result. |
| `candidate.provider_metrics.linktrail_corpus` | object | Required | linktrail corpus recorded for this result. additional fields rejected |
| `candidate.provider_metrics.linktrail_corpus.source_outlink_count` | integer / null | Required | source outlink count recorded for this result. |
| `candidate.provider_metrics.linktrail_corpus.source_external_outlink_count` | integer / null | Required | source external outlink count recorded for this result. |
| `candidate.provider_metrics.linktrail_corpus.fetch_kind` | string | Required | fetch kind recorded for this result. values: "direct", "rendered", "proxied" |
| `candidate.provider_metrics.linktrail_corpus.extraction_complete` | boolean | Required | extraction complete recorded for this result. |
| `candidate.verification_status` | string | Required | Linktrail check state, independent of supplier flags. not\_checked means no Linktrail check is recorded. values: "not\_checked", "present", "absent", "unknown", "source\_unavailable" |
| `candidate.verified_at` | string / null | Required | Timestamp of the Linktrail check; null until checked. |
| `candidate.observation_id` | string / null | Required | observation id recorded for this result. |
| `job` | object | Required | job recorded for this result. |
| `job.id` | string | Required | Resource identifier returned by the operation. |
| `job.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
| `job.execution_mode` | string | Required | execution mode recorded for this result. |
| `job.error_code` | string / null | Required | error code recorded for this result. |
| `job.created_at` | string | Required | UTC timestamp when the record was created. |
| `job.completed_at` | string / null | Required | completed at recorded for this result. |
| `job.usage` | object | Required | usage recorded for this result. |
| `job.usage.unit` | string | Required | unit recorded for this result. must equal "source\_check" |
| `job.usage.units` | number | Optional | units recorded for this result. |
| `job.usage.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `job.usage.period` | string | Optional | period recorded for this result. |
| `observation` | object / null | Required | observation recorded for this result. |
| `observation.id` | string | Required | Resource identifier returned by the operation. |
| `observation.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
| `observation.reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
| `observation.checked_at` | string | Required | UTC timestamp of the saved check. |
| `watch` | object | Required | watch recorded for this result. |
| `watch.id` | string | Required | Resource identifier returned by the operation. |
| `watch.status` | string | Required | Resource lifecycle status. |
| `watch.local_reference` | string / null | Required | Customer reference for joining this record to a local ledger entry. |
| `recurring_monitoring_created` | boolean | Required | Whether this operation enrolled recurring monitoring. must equal false |
| `replayed` | boolean | Optional | True when the response reuses an earlier request with the same idempotency value. |
[Download input schema](/schemas/verify_discovery_candidate.input.json) · [Download output schema](/schemas/verify_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/runs/{runId}/candidates/{candidateId}/verify` | 202 | Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route. |
## Continue
[get\_candidate\_verification](/reference/commands/get_candidate_verification)
Follow the [related workflow](/guides/import-and-verify), inspect [capability status](/capability-status), or return to the [command index](/reference/index).