# Prospecting extensions

> Explore bounded continuation Jobs and immutable qualification rubrics without treating either contract as GA.

Canonical guide: <https://engine.neraperla.com/docs/prospecting-extensions>

Raw Markdown: <https://engine.neraperla.com/docs/raw/prospecting-extensions.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

These Prospecting extensions are Preview. They are useful for integration testing, but their contracts may change incompatibly. Build the GA workflow around [Prospecting](https://engine.neraperla.com/docs/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.

```bash
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.
