> ## 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.

# Propose competitors with reasons

> Save up to 10 proposed competitors, each with its relationship, audience, topic and evidence pages.

`propose_competitors`

Save up to 10 proposed competitors, each with its relationship, audience, topic and evidence pages. Rejected sites stay rejected. Does not add them to the set or start lookups.

> [!NOTE]
>
> Hosted availability unverified: this name is absent from the 2026-10-27 deployment evidence. Check your connected catalog before calling. Provider configuration and workspace access still apply.

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

This operation changes saved state. Review its inputs and retry behavior before calling.

## Example request

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

```json MCP theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "propose_competitors",
    "arguments": {
      "projectId": "prj_example",
      "candidates": [
        {
          "domain": "rival-example.com",
          "rationale": {
            "relationship": "shared_backlink_neighbor",
            "audience": "Estate executors",
            "topic": "Probate checklists",
            "evidence": [
              {
                "source_url": "https://publisher.example.org/resources",
                "note": "Listed beside example.com"
              }
            ]
          }
        }
      ]
    }
  }
}
```

```bash CLI theme={null}
agentlinkops call propose_competitors --args '{"projectId":"prj_example","candidates":[{"domain":"rival-example.com","rationale":{"relationship":"shared_backlink_neighbor","audience":"Estate executors","topic":"Probate checklists","evidence":[{"source_url":"https://publisher.example.org/resources","note":"Listed beside example.com"}]}}]}'
```

```bash HTTP theme={null}
curl --fail-with-body https://app.agentlinkops.com/v1/commands/propose_competitors \
  -H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"projectId":"prj_example","candidates":[{"domain":"rival-example.com","rationale":{"relationship":"shared_backlink_neighbor","audience":"Estate executors","topic":"Probate checklists","evidence":[{"source_url":"https://publisher.example.org/resources","note":"Listed beside example.com"}]}}]}'
```

## Returned result

Schema-validated example; IDs and dates are illustrative. MCP returns this data in `structuredContent` and in a text content block; generic HTTP and CLI return the JSON result directly.

```json theme={null}
{
  "project_id": "prj_example",
  "results": [
    {
      "domain": "next.example",
      "outcome": "proposed"
    },
    {
      "domain": "unrelated.example",
      "outcome": "previously_rejected",
      "decided_at": "2026-10-19T08:00:00.000Z"
    }
  ],
  "spend": {
    "supplier_requests": 0,
    "credits": 0,
    "checks": 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 | project ID from create/list. minLength: `1`; maxLength: `128`; pattern: `"^[A-Za-z0-9_-]+$"` |
| `candidates` | array | Required | minItems: `1`; maxItems: `10` |
| `candidates[].domain` | string | Required | minLength: `3`; maxLength: `300` |
| `candidates[].rationale` | object | Required | additional fields rejected |
| `candidates[].rationale.relationship` | string | Required | values: `"business"`, `"search"`, `"shared_backlink_neighbor"`, `"unknown"` |
| `candidates[].rationale.audience` | string / null | Required | |
| `candidates[].rationale.topic` | string / null | Required | |
| `candidates[].rationale.evidence` | array | Required | maxItems: `5` |
| `candidates[].rationale.evidence[].source_url` | string | Required | minLength: `1`; maxLength: `2048` |
| `candidates[].rationale.evidence[].note` | string | Required | minLength: `1`; maxLength: `1000` |
| `candidates[].expectedRevision` | integer / null | Optional | |
| `candidates[].expectedSnapshot` | string / null | Optional | |

### Validation and omitted values

Saves up to ten proposals, each with its relationship, audience, topic and up to five evidence pages. A proposal never changes the approved set or starts a lookup; the person adds it through the competitor set.

Each result names its outcome: proposed, updated, unchanged (the same reason again), already\_a\_competitor, your\_website, previously\_rejected, duplicate\_in\_request or suggestion\_limit\_reached. A rejected site stays rejected until decide\_competitor\_suggestion restores it. The 50-suggestion limit counts proposals not yet in the set.

A candidate may include expectedRevision and expectedSnapshot from the same saved suggestion. Supply both together; null for both requires absence. A changed row, active set revision or proposal count returns 409 COMPETITOR\_SUGGESTION\_CHANGED and rolls back the whole batch. Read the current suggestions and set before trying again.

## Output fields

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

| Field | Type | Presence | Meaning and constraints |
| - | - | - | - |
| `project_id` | string | Required | Project that owns this record. |
| `results` | array | Required | |
| `results[].domain` | string | Required | |
| `results[].outcome` | string | Required | values: `"proposed"`, `"updated"`, `"unchanged"`, `"already_a_competitor"`, `"your_website"`, `"previously_rejected"`, `"duplicate_in_request"`, `"suggestion_limit_reached"` |
| `results[].decided_at` | string / null | Optional | |
| `spend` | object | Required | |
| `spend.supplier_requests` | number | Required | must equal `0` |
| `spend.credits` | number | Required | must equal `0` |
| `spend.checks` | number | Required | must equal `0` |

[Download input schema](https://docs.agentlinkops.com/schemas/propose_competitors.input.json) · [Download output schema](https://docs.agentlinkops.com/schemas/propose_competitors.output.json)

## Errors and retries

This write is annotated idempotent without a caller-supplied idempotency key. Reconcile saved state after an uncertain response, then use the same inputs for the same intended operation. Do not add an unsupported key. Operation-specific errors include `INVALID_COMPETITOR_SUGGESTION_INPUT`, `COMPETITOR_SUGGESTIONS_UNAVAILABLE`, `READ_ONLY_MEMBER`, `PROJECT_NOT_FOUND`.

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

## HTTP resource routes

This operation has no separate resource alias. Use its generic command route in a matching environment.

## Continue

[suggest\_competitors](https://docs.agentlinkops.com/reference/commands/suggest_competitors.md)

Follow the [related workflow](https://docs.agentlinkops.com/guides/competitor-research.md). See [capability status](https://docs.agentlinkops.com/capability-status.md) for availability or the [command index](https://docs.agentlinkops.com/reference/index.md) for another operation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.