Create a prospect list

POST/api/v2/websets

Creates a company or person prospect list from natural-language criteria. The endpoint returns HTTP 202; criteria generation, search, and verification continue asynchronously.

Request

Requires websets:write. Send an Idempotency-Key when requests may be retried, and reuse the original value after a network timeout.

Field	Type	Required	Description
`query`	string	Yes	Natural-language criteria, up to 2,000 characters.
`title`	string	No	List name, up to 200 characters.
`count`	integer	No	`25`, `100`, `500`, or `1000`; defaults to `25` and is plan-limited.
`target_kind`	string	No	`company` or `person`; defaults to `company`.
`locale`	string	No	`en` or `zh`; defaults to `en`.

cURL

curl -X POST "https://revor.ai/api/v2/websets" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Idempotency-Key: webset-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Excavator manufacturers, dealers, and rental providers in North America",
    "title": "North American excavator companies",
    "count": 25,
    "target_kind": "company",
    "locale": "en"
  }'

Response

JSON
{
  "ok": true,
  "request_id": "req_xxx",
  "webset": {
    "id": "webset-uuid",
    "status": "generating_criteria",
    "count": 25,
    "target_kind": "company"
  },
  "preparation_job": {
    "id": "job-uuid",
    "status": "queued"
  }
}

Save webset.id. HTTP 202 and preparation_job.status=queued mean the request was accepted, not that discovery is complete. Fetch an Items snapshot, then open Items SSE.

Errors

HTTP	Code	Description
`400`	`webset_query_required` / `webset_query_too_long`	The query is missing or too long.
`400`	`webset_count_invalid`	The requested count is not allowed.
`400`	`webset_target_kind_unsupported`	The target kind is invalid.
`403`	`webset_count_not_available_for_tier`	The current plan does not allow this count.
`409`	`idempotency_conflict`	The same idempotency key was used for another request.