Prospector API

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

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

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

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

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

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:

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:

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.