GeniPath API reference
The GeniPath API runs the idea-to-blueprint pipeline inside your own product. Your backend calls it; your customers stay in your product — they never see GeniPath, never log in, and never hold a key.
The model in brief
Balance, not subscription. Your API account carries a prepaid credit balance. There is no monthly plan and no free tier. Each stage has its own endpoints and its own credit price, charged from your balance when your backend enters the stage; message turns inside an entered stage are included. Auto top-off (optional): set a threshold and a top-up amount in your dashboard, keep a card on file, and the balance refills itself when a charge drops it below your threshold — you choose both numbers.
Base URL: https://imfaozheltoyowbthtkj.supabase.co/functions/v1/api-partner/v1
Every call: Authorization: Bearer gpk_live_…
Content type: application/jsonCreate and revoke keys, set your webhook, manage auto top-off and watch analytics in your partner dashboard. Keys are shown once at creation and stored only as hashes.
Authentication
All machine endpoints require your API key as a Bearer token, server-side only — never ship a key in browser or mobile code. A missing or unknown key returns 401 unauthorized; a revoked key returns 401 with error key_revoked.
Stage 1 — Discovery
Discovery turns a customer's rough idea into a structured idea_brief. What you provide: your own identifier for the customer (customer_ref, recommended), an optional session title, and the customer's first message.
POST /discovery
Opens a session and charges the Discovery price from your balance.
Body: { customer_ref?, title?, initial_message? } — with initial_message, the agent's first_reply comes back in the same response.
Returns 201: { session, session_id, first_reply, charged, charge_amount, balance }.
POST /discovery/{session_id}/messages
Body: { message }. Returns the agent's reply plus stage_complete and, when the stage finishes, the idea_brief.
Stage 2 — Feasibility
Feasibility scores the captured idea and returns a feasibility_brief with a go / no-go verdict. What you provide: a session whose Discovery is complete (stage_complete seen, idea_brief present) — nothing else is required.
POST /feasibility/{session_id}
Enters the stage and charges the Feasibility price.
Body (all optional): { message?, kickoff? } — send your own first message, or let the stage kick off from the idea brief (default). { "kickoff": false } enters without a first turn.
Entering before Discovery completes returns 409 discovery_incomplete.
POST /feasibility/{session_id}/messages
Body: { message }. Completion returns stage_complete: true, the feasibility_brief and the verdict.
Stage 3 — Specification
Specification produces the deliverable: the complete Genesis Master Build Prompt. What you provide: a session whose Feasibility is complete.
POST /specification/{session_id}
Enters the stage and charges the Specification price. Body mirrors Feasibility: { message?, kickoff? }. Entering early returns 409 feasibility_incomplete.
When the prompt is ready, replies carry master_prompt_ready: true and the session status becomes completed. Further messages to this endpoint are how revisions work.
POST /specification/{session_id}/messages
Body: { message }.
Reading state
GET /sessions/{session_id}
Full state: stage, both briefs, master_build_prompt, status, and the complete transcript (messages).
GET /sessions/{session_id}/export
The completed blueprint as a ready-to-import file for GenWhisperer: the same JSON envelope the GeniPath app exports (format "genipath-blueprint", version 1, with the project briefs, the master_build_prompt and instructions_for_agent). Returns 409 blueprint_not_ready until the Specification stage has produced the master prompt.
GET /sessions?customer_ref=&limit=50
Your sessions, newest first — filter by your customer_ref.
GET /agents
The three stages with their current credit prices and a summary of what each endpoint needs from you.
Balance & usage
GET /balance
{ balance_credits, stage_prices: { discovery, feasibility, specification }, auto_top_off: { enabled, threshold_credits, topup_amount_credits, has_card, last_reload_at, last_error } }
GET /usage
Requests (30 days), session count, and credits consumed in total and per stage.
A stage entry your balance cannot cover returns 402 insufficient_balance with the current balance and the required amount, and charges nothing. Charges are transactional: if a stage entry fails for any reason, its charge is refunded automatically.
Webhooks
Set one webhook URL per account in the dashboard and choose events: session.created, stage.advanced, credit.consumed, blueprint.ready. Deliveries are JSON POSTs signed with your webhook secret:
X-GeniPath-Signature: sha256=<HMAC-SHA256 hex of the raw body, keyed with your secret>
{
"id": "…", "event": "blueprint.ready", "created_at": "…",
"agency_id": "…", "session_id": "…",
"data": { "master_build_prompt": "…", "customer_ref": "…", "external_ref": "…" }
}Verify the signature against the raw request body before trusting a delivery. Delivery is best-effort (5s timeout, no retries in v1) and every attempt is logged — reconcile important events with GET /sessions/{id}.
Errors
401 unauthorized / key_revoked Check or replace the API key
402 insufficient_balance Balance too low for that stage — top up
403 agency_inactive Account not active — contact support
404 session_not_found Wrong id, or not your session
409 blueprint_not_ready No completed blueprint yet — finish Specification
409 discovery_incomplete Finish Discovery before Feasibility
409 feasibility_incomplete Finish Feasibility before Specification
409 stage_mismatch Session is not in that stage
409 stage_already_passed Session moved past that stage
413 prompt_too_long Shorten the message
429 rate_limited Over 120 req/min — back off
429 daily_limit_reached Customer's daily cap; resets 00:00 UTC
502 agent_error Transient — retry the turnLimits
120 requests per minute per API key. Messages up to ~24,000 characters. Each of your customers (per customer_ref) has a daily usage ceiling inside the pipeline that bounds inference cost; it resets at midnight UTC.
Getting access
API access activates self-serve: a one-time $1,299 activation including 100 credits of starting balance — activate here. Existing GeniPath customers (individual or agency) activate with their usual email and the API attaches to their existing account and login; their app credits and agency paths remain separate and are never spent by the API. See the API page or contact support@genipath.com. Partners manage everything from the partner dashboard, which includes a searchable copy of this guide.