Pilot5 over HTTPS.

When to use the REST API

Every deliberation Pilot5 runs is reachable over plain HTTPS. If your integration doesn’t go through an MCP client — a workflow tool, a custom dashboard, an internal Slack bot, a Zapier-style automation, a server-side cron — the REST API gives you the same surface without the connector hop.

If you’re wiring Pilot5 into Claude, Cursor, Perplexity, or another MCP-compatible client, the MCP connector is the simpler path.

Base URL & auth

• Base URL: https://api.pilot5.ai
• Auth: Authorization: Bearer <clerk_jwt> — sign in to pilot5.ai and copy your JWT from the dashboard, or use a service token issued by Clerk for server-side integrations.
• All endpoints are ownership-checked — you can only read deliberations launched by your own user / org.

Launch a deliberation

POST /v1/deliberations
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "question": "Should we raise pricing 12% across the SaaS portfolio?",
  "mode": "deliberation1",         // smartroute1 | deliberation1 | deliberation2
  "use_case": "pricing",           // optional — auto-detected if omitted
  "difficulty": "MEDIUM",          // optional — auto-classified if omitted
  "context": "..."                 // optional free-text framing
}

→ 202 Accepted
{ "deliberation_id": "uuid", "status": "pending", "estimated_credits": 4.2 }

Returns immediately with a deliberation ID. Credits are reserved (not yet debited) at the estimated amount; the final charge is computed from actual token usage and the excess is refunded.

Watch it run

The A-Team takes ~ 7 minutes; The Dream Team ~ 12–18. Three ways to follow progress:

• GET /v1/deliberations/{id}/stream — Server-Sent Events stream. Real-time persona-completed / round-completed events. Best for responsive UIs.
• GET /v1/deliberations/{id}/events — full event timeline as JSON. Best for polling or post-hoc audit.
• GET /v1/deliberations/{id} — latest snapshot of the structured record. Includes a status field: pending / running / awaiting_feedback / completed / failed.

Steer The Dream Team

When the deliberation pauses for HITL the status flips to awaiting_feedback. Submit your steering input via:

POST /v1/deliberations/{id}/feedback
{
  "feedback": "Focus the next round on EU mid-market churn data.
               Stripe Atlas excludes EU SaaS — sample bias."
}

→ 200 OK    // resumes the deliberation

Free-text, 1–2000 chars. Submit-once-per-pause is enforced via compare-and-set; concurrent submits return 409 Conflict.

Close the loop on predictions

Pilot5 extracts testable predictions during synthesis (with timelines like 90 days or Q3 2026). Log observed outcomes later via:

POST /v1/deliberations/{id}/outcome
{
  "prediction_index": 0,
  "outcome": "verified",            // verified | falsified | partial | unknown
  "evidence": "Churn dropped to 6% by Q2 2026; recommendation held."
}

Other endpoints

• GET /v1/deliberations — list past deliberations (paged, filterable by mode/status/use_case)
• GET /v1/deliberations/{id}/synthesis — synthesis output only
• GET /v1/deliberations/{id}/pdf — rendered PDF report
• POST /v1/deliberations/{id}/cancel — cancel a running deliberation
• POST /v1/deliberations/analyze — pre-launch question analysis (free, doesn't reserve credits)
• GET /api/stats — public, no auth. Returns the live trusted-source count and adapter tier breakdown.

Rate limits

Per-user limits at the API edge. Enforced via Redis sliding window; exceeded calls return 429 Too Many Requests with a Retry-After header.

• Launch deliberations: 20 / hour
• Submit feedback: 20 / minute
• Analyze (pre-launch): 20 / minute
• Resume a paused deliberation: 10 / hour
• Restart a deliberation: 3 / hour
• Render full PDF report: 5 / hour
• Chat assistant messages: 50 / hour

OpenAPI spec

A machine-readable OpenAPI 3.1 spec is published at /docs/api/openapi-ai-tool-generator.json. AI-tool-generator-ready, also consumable by Vertex AI Extension and any standard OpenAPI client.

Building a Gemini or Vertex Extension on top of Pilot5? Point it at the spec above and at the production base URL. Service-account JWTs are accepted alongside user-issued Clerk tokens.

Support

Questions or issues? Contact contact@pilot5.ai. Enterprise & DPAs: enterprise@pilot5.ai.

See also the Privacy Policy, Terms of Service, and Data Processing Agreement.