Documentation
How to call the Skeptral API: submit a pitch for a validation read, poll for the verdict, then scaffold a runnable Next.js app from the result.
Getting started
The API is a small REST surface under /api/v1. It does two things: it reads an idea and returns a verdict, and it scaffolds a Next.js app from an idea that cleared the read. Every call is authenticated with a bearer key. Responses are JSON, except the scaffold zip.
1. Get a key
The API turns on once a key is set. On a self-hosted instance you set it yourself: set IDEAGEN_API_TOKEN to a secret of your choice (the env name predates the Skeptral rebrand and is kept for compatibility; we suggest an ig_live_ prefix by convention) and the surface goes live. With no key set, every endpoint answers 401 and tells you the API isn't enabled.
# self-host: set the key, the API switches on IDEAGEN_API_TOKEN=ig_live_...
Self-serve key issuance from the dashboard is the multi-tenant path and isn't built yet. Hosted keys
2. Base URL and auth
Everything sits under /api/v1. Send your key on every request in the Authorization header. A missing or wrong key comes back as 401 JSON: { "error": "..." }.
Base URL: https://your-instance/api/v1 Header: Authorization: Bearer ig_live_...
3. Your first call
Submit a pitch. You get a job id back straight away, the read runs in the background.
curl -X POST https://your-instance/api/v1/validate \
-H "Authorization: Bearer ig_live_..." \
-H "Content-Type: application/json" \
-d '{ "idea_description": "A booking tool for mobile dog groomers." }'
# -> 202
{ "job_id": "val_1718...", "status": "processing", "estimated_completion_seconds": 60 }Core concepts
There's one flow to learn: submit a pitch, poll the job, read the verdict, then scaffold if it cleared. Here's each piece.
1. The validation job
A validation is a quick read, not a live-signal run: the model reasons over the pitch you send and nothing else. It does not gather live demand. That heavier path is the full pipeline, not this endpoint. The read is asynchronous, so the lifecycle is submit, poll, completed.
# submit
POST /api/v1/validate
-> 202 { "job_id": "val_1718...", "status": "processing",
"estimated_completion_seconds": 60 }
# poll every few seconds with the job id
GET /api/v1/validate/val_1718...
-> { "job_id": "val_1718...", "status": "processing" }
-> { "job_id": "val_1718...", "status": "completed", "result": { ... } }2. The result object
Once status is completed, the poll carries a result. The verdict is the headline: scale, pivot, or kill. The kill_shot is the single hardest objection the idea has to answer.
"result": {
"score": 0, // 0-100, the overall read
"verdict": "scale", // "scale" | "pivot" | "kill"
"kill_shot": "string",
"market": 0, // 0-100
"feasibility": 0, // 0-100
"moat": 0, // 0-100
"summary": "string"
}3. The scaffold step
When a read clears (anything that isn't a kill), hand the job_id to the scaffolder and get a runnable Next.js 15 app back: App Router, a typed Drizzle schema, CRUD routes, and Stripe wiring when the idea is a paid product. A zip by default, or the file manifest as JSON with "format": "json".
POST /api/v1/scaffold/nextjs
Authorization: Bearer ig_live_...
{ "job_id": "val_1718..." }
-> a downloadable .zip of the app
{ "job_id": "val_1718...", "format": "json" }
-> { "slug", "file_count", "spec", "files": [ ... ] }What isn't built yet Roadmap
Hosted key issuance from the dashboard and per-key rate-limit dashboards are still ahead. A self-hosted instance runs on the single key you set in the env. Everything documented on this page and the API reference is live and callable today.