API

The six endpoints you'll actually call.

Auth with a Firebase JWT or an X-API-Key. Idempotency on every billable POST. Credit cost previewed before any charge.

Auth

Two equivalent auth methods, one dependency.

Firebase JWT — Authorization: Bearer <token>. Validated against the project's Firebase Auth instance. The uid claim is the canonical user id. Use this from a browser session.
API Key — X-API-Key: ipz_<32 base64 chars>. Looked up by SHA-256 hash in Firestore. Free-plan users get rejected. Use this for server-to-server.
Idempotency — send X-Idempotency-Key on every billable POST. A retried request with the same key returns the original response and never double-charges.

Endpoints

Method	Path	Auth	Cost	Rate
POST	/api/v1/ip-radar/scope-query Free-text brief → structured DrugBrief + multi-strategy SearchPlan preview. Used to dry-run the research before charging credits.	Firebase JWT or X-API-Key	10 credits	10/min
POST	/api/v1/ip-radar/research/start Boot an async research job. Returns a job_id immediately; the streaming orchestrator runs in a background task. Subtasks land in Firestore as they complete.	Firebase JWT or X-API-Key	300 credits (per 100 patents read)	2/hour
GET	/api/v1/ip-radar/research/{id} Poll job state. Returns the progress map, the per-subtask results, and (when done) the final landscape + FTO report. Cheap; safe to poll every 2–5 s.	Firebase JWT or X-API-Key	Free	60/min
GET	/api/v1/ip-radar/research/{id}/export.zip Download a self-contained ZIP — DataTables dashboard, per-drug accordion, FTO panel, entity blocks, watermarked. Suitable for archival or offline review.	Firebase JWT or X-API-Key	Free	60/min
POST	/api/v1/ip-radar/deep-scan Bulk patent analysis — process 500 to 15,000 patents in one job. Carved out from the standard research flow because the job pool and progress polling don't fit the request/response shape.	Firebase JWT or X-API-Key	1,500 credits (per 1,000 patents)	1/hour
GET	/api/v1/status Health probe. Returns service name, version, status, and the list of mounted endpoints. Used by Cloud Run health checks and uptime monitors.	Public	Free	—

Example — boot a scope query

A scope query is the cheapest way to dry-run a research request. It parses the brief, plans a multi-strategy search, returns a credit estimate and a runtime estimate — and locks the plan behind a plan_id you can pass to /research/start.

bash

# 1. Get a Firebase ID token (or use an API key — both work).
TOKEN="$(curl -s ... | jq -r .id_token)"
IDEMPOTENCY_KEY="$(uuidgen)"

# 2. Scope a brief — returns a SearchPlan + cost preview.
curl -X POST https://app.ipzilla.app/api/v1/ip-radar/scope-query \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "X-Idempotency-Key: $IDEMPOTENCY_KEY" \
     -d '{
       "brief": "amorphous solid dispersion of indomethacin in PVPVA copolymer, oral bioavailability target",
       "jurisdictions": ["US", "EP", "JP", "CN"],
       "depth": "deep_scan"
     }'

# Expect: 200 OK
# {
#   "plan_id": "plan_01HZAB...",
#   "estimated_credits": 312,
#   "estimated_runtime_seconds": 480,
#   "search_strategies": [
#     {"id": "s1", "type": "molecule_lexical", "queries": [...]},
#     {"id": "s2", "type": "formulation_class", "queries": [...]},
#     {"id": "s3", "type": "indication_xref", "queries": [...]}
#   ],
#   "drug_brief": { "actives": ["indomethacin"], "polymers": ["PVPVA"], ... }
# }

Need the full reference?

Every payload schema, every error code, every webhook — including the long-tail endpoints (templates, batch, jobs index, drug shortlist) — lives behind auth.