Valcour Ad-Targeting API

post/api/v1/ai/ad-targeting/opportunity

Rank geographies by ad-targeting opportunity.

Scores geographies as reach × favorability × audience-fit ÷ (1 + ad-saturation), built from public data sources (Census ACS, Meta Ad Library, Google Political Ads, FEC). Reach (audience size) is a first-class term so large markets are not zeroed out by a low percentage. Fail-soft per source: any source returning nothing is listed in data_sources_unavailable, and a best-effort ranking is still produced.

Request body

Responses

• 200 Ranked geographies with scores, confidence bands, and source provenance.
  • racestring · nullable
  • statestring · nullable
  • resultsrequiredarray
    array of:

    • geographyrequiredstring
      The geography being scored (e.g. a county).
    • opportunity_scorerequirednumber
      Point opportunity score.
    • ci_lowrequirednumber
      5th-percentile bound of the confidence band.
    • ci_highrequirednumber
      95th-percentile bound of the confidence band.
    • competitivenessrequirednumber · min 0 · max 1
    • persuadable_densityrequirednumber · min 0 · max 1
    • ad_saturationrequirednumber · min 0 · max 1
    • whyrequiredstring
      Short explanation of why this geography ranked where it did.
    • componentsrequiredobject
      The underlying component values that produced the score.
  • competitiveness_sourcerequiredstring
    How competitiveness was derived (e.g. a historical-lean proxy).
  • data_sources_usedrequiredarray
    Data sources that contributed to this ranking.
    array of:

    string
  • data_sources_unavailablerequiredarray
    Data sources that returned nothing for this request.
    array of:

    string
  • notesrequiredarray
    Plain-language caveats about how the ranking was produced.
    array of:

    string
• 401 unauthorized — missing or invalid bearer token
• 422 invalid request body
• 429 rate limited

Try it

curl -X POST \
  'https://valcour-ad-targeting.vercel.app/api/v1/ai/ad-targeting/opportunity' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ /* see request body schema above */ }'

post/api/assistant/chat

Ask the targeting assistant a question (streaming).

Same-origin proxy to the assistant. Send a message; the response is a Server-Sent Events (SSE) stream of the assistant's reply, including any tool runs (such as the opportunity ranking). This is the endpoint the public /chat page uses. Unauthenticated and rate-limited per IP.

Request body

Responses

• 200 text/event-stream of assistant events (text deltas, tool_start, tool_result).
• 400 invalid input
• 429 rate limited
• 503 assistant temporarily unavailable

Try it

curl -X POST \
  'https://valcour-ad-targeting.vercel.app/api/assistant/chat' \
  -H 'Content-Type: application/json' \
  -d '{ /* see request body schema above */ }'

get/api/health

DB-deep liveness probe.

Responses

• 200 Service healthy — database reachable.
• 503 Service unhealthy — database unreachable.

Try it

curl -X GET \
  'https://valcour-ad-targeting.vercel.app/api/health'