v1 recipes LIVE

the three endpoints

Save returns 201 with recipe_id (r_ + 24 hex chars), recipe_version (today: 1), name (your name, sliced to 120 chars, or the recipe's own name), signals, parcels_in_scope, and stored_via (d1 when the binding is present, memory otherwise).

the recipe object — exact validated shape

{
  "geography": {
    "type": "parcel_list",          // county_list | radius | parcel_list | bounding_box
    "parcel_keys": [                // required for parcel_list
      { "state_fips": "51", "county_fips": "087", "apn_normalized": "E-123-4" }
    ]
  },
  "signals": [                      // non-empty array; each entry needs a signal name
    { "signal": "absentee_high_equity", "params": { } }
  ],
  "logic": {
    "exclusions": [                 // evaluated AND billed like any signal
      { "signal": "recent_buyer", "params": { } }
    ]
  }
}

• parcel keys are exact: state_fips must be a 2-digit FIPS string, county_fips a 3-digit FIPS string, apn_normalized a non-empty string of 64 chars or fewer (trimmed). No address or lat/lng normalization — a parcel key is the only addressable unit.
• signal resolution: an unknown name returns 400 unknown_signal; a name in the 228-signal catalog with no working v1 adapter returns 404 signal_not_built — the 228 count is not a working-API count.
• exclusions are evaluated and billed like any other signal (nSignals counts them) — the compiler adds them to the resolved signal list before computing calls.
• per-signal params merge from signals[].params and logic.exclusions[].params; each adapter receives exactly its own params at run time.

compile-time errors

geography: exact vs streaming LIVE

MVP geography support is honest about what resolves:

The estimate carries its own hint: "note": "Streaming geography: pass parcel_list geography for an exact pre-run figure." Streaming run execution is planned, not shipped (see DRAFT below).

the estimate binds the charge

Every estimate response carries: api_version (v1), estimate_id (est_ + 24 hex chars), recipe_hash (sha256 over the recursively key-sorted recipe JSON — stable regardless of key insertion order), recipe_version, parcels_in_scope, signals, calls_estimated, cost_estimated_usd, price_per_call_usd (0.003, modeled), plan_coverage, quota, and the idempotency note "Re-running within 24h with the same recipe version costs $0 additional (idempotency)."

• plan coverage: included_remaining, overage_calls (calls above remaining quota — with overage_cost_usd: 0 because the free tier is a hard stop, never billed over), fits_quota, and the note "Free tier: hard stop at quota, no overage billing."
• the large-run gate: runs above 1,000 calls require the estimate_id from POST /v1/recipes/estimate — without it, run returns 400 bad_params with an estimate_required: message. No blind execution.
• estimate validation: run re-hashes the stored recipe and compares — a stale or mismatched estimate fails with 409 bad_params carrying an estimate_mismatch: message ("this estimate was computed for a different recipe version").
• the credit rule: when estimate_id binds, the billing block carries credit_calls = max(0, calls_estimated − calls_completed) and credit_usd at the modeled price. Failed evaluations are never charged, so anything the estimate assumed but execution didn't complete is credited explicitly.

execution: pages, quota, and what bills

• pages: runs page through parcels at 1,000 parcels per page (PAGE_PARCELS). The response carries pagination: { cursor, next_cursor, parcels_total, parcels_in_page } — pass next_cursor back as cursor for the next page. The idempotency scope includes the cursor, so each page has its own key scope.
• quota fits the whole page: the page's charge must fit inside remaining monthly quota, or the page is refused with 402 quota_exhausted and nothing is billed — no partial page billing.
• completed-only: each parcel's adapter is evaluated; a failed evaluation is itemized in results with error / error_code and billed: false. Only completed evaluations consume quota, and the response carries the note: "N evaluation(s) failed and were not billed; only completed evaluations consume quota."
• adapter contract check: an adapter returning match: true with a non-positive evidence_status (missing / not_covered / unresolved) is treated as a failure, not a match.
• rights block: every run response carries rights: { signal_license: "restricted", source_rights_verified: false }.
• replays: the same Idempotency-Key with the identical payload returns the stored response; the same key with a different payload is rejected with 409 idempotency_replay.

planned: streaming run execution DRAFT

county_list, radius, and bounding_box recipes estimate honestly today but cannot run — the parcel-inventory database does not exist, so POST /v1/recipes/{id}/run answers 400 geography_not_supported. When the inventory ships, these geographies execute with the same paged, per-page-billed, estimate-bound contract. The estimate's streaming shape (calls_estimated: null) will be replaced by a real pre-run figure — not final.

planned: bound charges for streaming geography DRAFT

Today the charge can only be bound for parcel_list recipes, because only they have an exact parcel count. Until the inventory ships, streaming-geography charges cannot be pre-bound — the per-page running-total reporting in estimate responses is the contract, and no exact total is printed because none is knowable. Exact binding rules for streaming geographies are not final.