> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-prospector.md).

# Prospector API

Read and manage saved Prospector outreach lists through the Agent API without triggering discovery, enrichment, scraping, or contact actions.

Use the Prospector Agent API to turn a known source or outreach opportunity into durable client workspace state. The API manages saved lists and their pipeline items only. It does not search for prospects, run backlink providers, enrich contacts, scrape pages, send email, or contact anyone.

## Scopes and safety

* `prospector:read` lists saved lists and items.
* `prospector:write` creates, updates, or deletes saved list state.
* Every mutation requires a stable `Idempotency-Key` header.
* Deletes also require the exact current list name or item URL in the request body.
* All routes verify both organization and client ownership. A foreign list or item is returned as not found.

## List saved outreach lists

```http
GET /api/agent/v1/clients/:client_id/prospect-lists?limit=25&offset=0
```

The response is newest-updated first and capped at 100 lists per page. Each row includes `item_count` and a `status_breakdown` for `identified`, `contacted`, `in_discussion`, `won`, and `passed` items.

## Create a list

```http
POST /api/agent/v1/clients/:client_id/prospect-lists
Idempotency-Key: client-citation-outreach-v1
Content-Type: application/json

{
  "name": "Citation outreach",
  "opportunity_type": "guest_post"
}
```

`opportunity_type` is optional. Reusing the same key returns the same durable list instead of creating another list.

## List pipeline items

```http
GET /api/agent/v1/clients/:client_id/prospect-lists/:list_id/items?status=identified&limit=50&offset=0
```

The response contains compact target identity, URL, opportunity type, status, notes, contact path, and timestamps. It does not include scraped content or raw enrichment payloads.

## Save one known prospect

```http
POST /api/agent/v1/clients/:client_id/prospect-lists/:list_id/items
Idempotency-Key: example-resources-outreach-v1
Content-Type: application/json

{
  "url": "https://example.com/resources/",
  "name": "Example resources",
  "status": "identified",
  "notes": "Potential citation-source update"
}
```

Rankability normalizes HTTP/HTTPS URLs, rejects private or unsafe hosts, and de-duplicates canonical URL variants within the list. Saving an item records workflow state only; it does not fetch the URL.

## Update pipeline state

```http
PATCH /api/agent/v1/clients/:client_id/prospect-lists/:list_id/items/:item_id
Idempotency-Key: example-resources-status-v2
Content-Type: application/json

{
  "status": "contacted",
  "notes": "Sent through the customer's approved external workflow"
}
```

Send at least one of `status` or `notes`. Set `notes` to `null` to clear it. This endpoint records what happened elsewhere; it never sends outreach.

## Delete an item or list

Deleting an item requires the exact `url` returned by the item list:

```http
DELETE /api/agent/v1/clients/:client_id/prospect-lists/:list_id/items/:item_id
Idempotency-Key: example-resources-delete-v1
Content-Type: application/json

{
  "confirm_url": "https://example.com/resources/"
}
```

Deleting a list requires its exact current name:

```http
DELETE /api/agent/v1/clients/:client_id/prospect-lists/:list_id
Idempotency-Key: citation-outreach-delete-v1
Content-Type: application/json

{
  "confirm_name": "Citation outreach"
}
```

List deletion removes memberships and the list. It does not delete pages, external contacts, or unrelated Rankability evidence.