> ## 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.
# Import link watches
> Import up to 100 known backlinks.
`import_link_watches`
Import up to 100 known backlinks. Each row returns its position and success or error. accepted includes existing placements; created counts only new watches. Invalid rows do not prevent valid rows from being imported.
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 |
| --------------- | --------------------- |
| `watches:write` | Writes or admits work |
Reading saved data does not start a verification job. Mutations can change saved records or access; the effects below apply.
## 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": "import_link_watches",
"arguments": {
"projectId": "project_example",
"watches": [
{
"sourceUrl": "https://publisher.example.com/resources",
"targetUrl": "https://example.com/guide"
}
]
}
}
}
```
```bash CLI theme={null}
linktrail call import_link_watches --args '{"projectId":"project_example","watches":[{"sourceUrl":"https://publisher.example.com/resources","targetUrl":"https://example.com/guide"}]}'
```
```bash HTTP theme={null}
curl "$LINKTRAIL_API_URL/v1/commands/import_link_watches" \
-H "Authorization: Bearer $LINKTRAIL_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"projectId":"project_example","watches":[{"sourceUrl":"https://publisher.example.com/resources","targetUrl":"https://example.com/guide"}]}'
```
## 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}
{
"status": "succeeded",
"rows": [
{
"index": 0,
"watch": {
"workspace_id": "ws_example",
"project_id": "project_example",
"status": "active",
"cadence_seconds": 86400,
"state": "unknown",
"observation_state": {},
"created_at": "2026-09-13T12:00:00.000Z",
"updated_at": "2026-09-13T12:00:00.000Z",
"last_attempt_at": null,
"last_success_at": null,
"last_observation_id": null,
"next_check_at": "2026-09-13T12:00:00.000Z",
"overdue_reason": null,
"id": "watch_example_1",
"source_url": "https://publisher.example.com/resources",
"target_url": "https://example.com/guide",
"target_scope": "exact",
"expected_anchor": null,
"expected_rel": null,
"local_reference": null,
"last_successful_observation_id": null,
"created": true
}
}
],
"imported": 1,
"accepted": 1,
"created": 1,
"existing": 0,
"failed": 0
}
```
## 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 |
| -------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId` | string | Required | Identifier of the project returned by its create or list operation. minLength: 1; maxLength: 200 |
| `watches` | array | Required | Rows use sourceUrl and targetUrl, plus optional targetScope, cadenceSeconds, expectedAnchor, expectedRel and localReference. Each invalid row returns an error at its position; valid rows continue. minItems: 1; maxItems: 100 |
| `watches[].sourceUrl` | string | Required | See the typed schema and response example for this field. format: "uri" |
| `watches[].targetUrl` | string | Required | See the typed schema and response example for this field. format: "uri" |
| `watches[].targetScope` | string | Optional | See the typed schema and response example for this field. values: "exact", "domain", "subdomain", "path" |
| `watches[].cadenceSeconds` | integer | Optional | See the typed schema and response example for this field. minimum: 3600; maximum: 2592000 |
| `watches[].expectedAnchor` | string / null | Optional | See the typed schema and response example for this field. |
| `watches[].expectedRel` | array / null | Optional | See the typed schema and response example for this field. |
| `watches[].localReference` | string | Optional | See the typed schema and response example for this field. maxLength: 200 |
### Validation and omitted values
Each watch row uses monitor\_link defaults: targetScope exact and cadenceSeconds 86400 when omitted; omitted expectations and localReference are empty.
Each row is processed separately. Invalid rows produce indexed errors while valid rows continue. accepted includes reused watches; created counts only new watches.
Relation expectations allow at most twenty tokens, each one to forty letters, digits, `_` or `-`; values are lowercased, deduplicated and sorted.
## 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 |
| --------------------------------------------------------------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `status` | string | Required | Resource lifecycle status. |
| `rows` | array | Required | rows recorded for this result. |
| `rows[].index` | number | Required | index recorded for this result. |
| `rows[].watch` | object | Optional | watch recorded for this result. |
| `rows[].watch.id` | string | Required | Resource identifier returned by the operation. |
| `rows[].watch.workspace_id` | string | Required | Workspace that owns this record. |
| `rows[].watch.project_id` | string | Required | Project that owns this record. |
| `rows[].watch.status` | string | Required | Resource lifecycle status. values: "active", "paused" |
| `rows[].watch.cadence_seconds` | number | Required | cadence seconds recorded for this result. |
| `rows[].watch.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
| `rows[].watch.observation_state` | object | Required | Saved observation state. Before the first check, this object can be empty. |
| `rows[].watch.observation_state.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `rows[].watch.observation_state.uncertain` | boolean | Optional | uncertain recorded for this result. |
| `rows[].watch.observation_state.checked_at` | string | Optional | UTC timestamp of the saved check. |
| `rows[].watch.observation_state.lastChangedAt` | string / null | Optional | last Changed At recorded for this result. |
| `rows[].watch.observation_state.firstAbsentAt` | string / null | Optional | first Absent At recorded for this result. |
| `rows[].watch.observation_state.consecutiveAbsent` | number | Optional | consecutive Absent recorded for this result. |
| `rows[].watch.observation_state.nextCheckAt` | string / null | Optional | next Check At recorded for this result. |
| `rows[].watch.observation_state.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `rows[].watch.observation_state.latestAttempt` | object / null | Optional | latest Attempt recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `rows[].watch.observation_state.latestAttempt.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `rows[].watch.observation_state.latestAttempt.checkedAt` | string | Optional | checked At recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.httpStatus` | number / null | Optional | http Status recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrenceCount` | number | Optional | occurrence Count recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences` | array | Optional | occurrences recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].href` | string / null | Optional | href recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].targetUrl` | string / null | Optional | target Url recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].anchor` | string / null | Optional | anchor recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].rel` | array | Optional | rel recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].context` | string / null | Optional | context recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].locator` | object / null | Optional | locator recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].locator.line` | number / null | Optional | line recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].locator.column` | number / null | Optional | column recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.occurrences[].locator.offset` | number / null | Optional | offset recorded for this result. |
| `rows[].watch.observation_state.latestAttempt.checkerVersion` | string | Optional | checker Version recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation` | object / null | Optional | last Successful Observation recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `rows[].watch.observation_state.lastSuccessfulObservation.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `rows[].watch.observation_state.lastSuccessfulObservation.checkedAt` | string | Optional | checked At recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.httpStatus` | number / null | Optional | http Status recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrenceCount` | number | Optional | occurrence Count recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences` | array | Optional | occurrences recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].href` | string / null | Optional | href recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].targetUrl` | string / null | Optional | target Url recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].anchor` | string / null | Optional | anchor recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].rel` | array | Optional | rel recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].context` | string / null | Optional | context recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].locator` | object / null | Optional | locator recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].locator.line` | number / null | Optional | line recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].locator.column` | number / null | Optional | column recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.occurrences[].locator.offset` | number / null | Optional | offset recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservation.checkerVersion` | string | Optional | checker Version recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulObservationSameAsLatestAttempt` | boolean | Optional | last Successful Observation Same As Latest Attempt recorded for this result. |
| `rows[].watch.observation_state.confirmedState` | string / null | Optional | confirmed State recorded for this result. |
| `rows[].watch.observation_state.lastSuccessfulAt` | string / null | Optional | last Successful At recorded for this result. |
| `rows[].watch.observation_state.lastHealthyAt` | string / null | Optional | last Healthy At recorded for this result. |
| `rows[].watch.observation_state.firstUnavailableAt` | string / null | Optional | first Unavailable At recorded for this result. |
| `rows[].watch.observation_state.unavailableCount` | number | Optional | unavailable Count recorded for this result. |
| `rows[].watch.observation_state.wasEverHealthy` | boolean | Optional | was Ever Healthy recorded for this result. |
| `rows[].watch.observation_state.retryNotBefore` | string / null | Optional | retry Not Before recorded for this result. |
| `rows[].watch.observation_state.ignored` | boolean | Optional | ignored recorded for this result. |
| `rows[].watch.created_at` | string | Required | UTC timestamp when the record was created. |
| `rows[].watch.updated_at` | string | Required | UTC timestamp of the last record update. |
| `rows[].watch.last_attempt_at` | string / null | Required | last attempt at recorded for this result. |
| `rows[].watch.last_success_at` | string / null | Required | last success at recorded for this result. |
| `rows[].watch.last_observation_id` | string / null | Required | last observation id recorded for this result. |
| `rows[].watch.next_check_at` | string / null | Required | next check at recorded for this result. |
| `rows[].watch.overdue_reason` | string / null | Required | overdue reason recorded for this result. |
| `rows[].watch.source_url` | string | Required | Publisher page URL recorded in this evidence. |
| `rows[].watch.target_url` | string | Required | Destination URL recorded in this evidence. |
| `rows[].watch.target_scope` | string | Required | target scope recorded for this result. |
| `rows[].watch.expected_anchor` | string / null | Required | expected anchor recorded for this result. |
| `rows[].watch.expected_rel` | array / null | Required | expected rel recorded for this result. |
| `rows[].watch.local_reference` | string / null | Required | Customer reference for joining this record to a local ledger entry. |
| `rows[].watch.last_successful_observation_id` | string / null | Required | last successful observation id recorded for this result. |
| `rows[].watch.history_compacted_before` | string / null | Optional | history compacted before recorded for this result. |
| `rows[].watch.created` | boolean | Optional | True when this request created the record; false when an existing record was reused. |
| `rows[].watch.detail` | string | Optional | detail recorded for this result. |
| `rows[].error` | object | Optional | error recorded for this result. |
| `rows[].error.code` | string | Required | code recorded for this result. |
| `rows[].error.message` | string | Required | message recorded for this result. |
| `imported` | number | Required | imported recorded for this result. |
| `accepted` | number | Required | accepted recorded for this result. |
| `created` | number | Required | True when this request created the record; false when an existing record was reused. |
| `existing` | number | Required | existing recorded for this result. |
| `failed` | number | Required | failed recorded for this result. |
[Download input schema](/schemas/import_link_watches.input.json) · [Download output schema](/schemas/import_link_watches.output.json)
## Errors and retries
This command is not annotated idempotent. After a timeout, inspect existing state before repeating a write.
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/watches/import` | 201 | Remaining arguments go in a JSON object body. |
## Continue
[list\_link\_watches](/reference/commands/list_link_watches)
Follow the [related workflow](/guides/monitor-changes), inspect [capability status](/capability-status), or return to the [command index](/reference/index).