Prospecting extensions
Explore bounded continuation Jobs and immutable qualification rubrics without treating either contract as GA.
These Prospecting extensions are Preview. They are useful for integration testing, but their contracts may change incompatibly. Build the GA workflow around Prospecting, Jobs, and Outcomes first.
Create a bounded continuation#
Preview operation create_prospecting_continuation_v1_jobs__parent_job_id__continuations_post creates one immutable child of a succeeded real Prospecting Job. It does not mutate or resume the parent.
curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/jobs/$PARENT_JOB_ID/continuations" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"continuation_key": "more-anz-revops-20260717",
"additional_prospect_limit": 20,
"max_rounds": 2,
"min_new_prospects_per_round": 1
}'Use a continuation to get more results from a search you already ran, instead of running the same search again. A continuation of a run made by the prospect agent continues in that run's own search: each round is a follow-up asking the agent for that many more new prospects, with the companies the search already delivered listed as excluded. The child returns only prospects that search hasn't delivered (through the original run or any continuation of it), at most additional_prospect_limit of them. Rounds stop when the child has additional_prospect_limit new prospects (target_reached), when a round finds fewer than min_new_prospects_per_round (min_new_prospects_not_met), after max_rounds or when another round could not finish within the run's time limit (max_rounds_reached), or when a round is interrupted (provider_unavailable). Each round takes as long as a run, typically several minutes. The child's research trace reports each round, and it is charged like a run for the search work of every round. A continuation that finds nothing new fails and is not charged. A search runs one continuation at a time: creating another while one is queued or running returns 409 prospecting_continuation_in_progress. To keep going, continue the child once it finishes.
The parent and bearer key must share project and live/test environment. A company-level key needs no Blackpearl-Project header: the parent run selects the project, and the continuation is charged there. The parent must be a succeeded Prospecting Job with a valid normalized, non-synthetic result. The child binds the parent ID, result hash, normalized result snapshot, connection revision, and constraints so later changes cannot alter its provenance. Reusing the continuation key with the same request replays the child; changed constraints conflict.
Store qualification policy contracts#
Specification preview — this surface accepts and stores typed plans; execution is not yet available. No scorer exists: storing a policy never scores a prospect.
Preview operation create_qualification_policy_v1_qualification_policies_post stores an immutable five-dimension rubric. A policy freezes its target taxonomy, exact integer weights, evidence and freshness rules, score bands, and expected policy version. It does not score prospects or authorize downstream action.
Preview operation list_qualification_policies_v1_qualification_policies_get lists policies in the current project and environment with cursor pagination. Preview operation get_qualification_policy_v1_qualification_policies__qualification_policy_id__get reads one policy. Use the returned policy hash when a future executor requires optimistic binding; never infer that creating a policy means a scorer is available.
Preview resources should remain isolated behind a feature flag and observability boundary. Do not persist assumptions about their schema into irreversible workflows.