Skip to main content

​
Endpoint

POST /api/idea
Content-Type: application/json

​
Request Format

FieldTypeRequiredDescription
ideastringYesUser’s project idea (non-empty).
sessionIdstringNoExisting workflow session; if omitted, a new UUID is generated.

​
Example

{
  "idea": "A task manager for remote teams with kanban and time tracking.",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

​
Response Format

​
Success (200)

FieldTypeDescription
status"success"
sessionIdstringID to use for subsequent intent, platform, payment, execute.
stage"idea_input"
analysisobjectsummary, key_features[], complexity, estimated_agents.
clarifying_questionsstring[]3–5 questions.
next_stage"intent_analysis"

​
Example

{
  "status": "success",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "stage": "idea_input",
  "analysis": {
    "summary": "A task manager for remote teams with kanban and time tracking.",
    "key_features": ["kanban board", "time tracking", "remote collaboration"],
    "complexity": "medium",
    "estimated_agents": 4
  },
  "clarifying_questions": [
    "Which platforms: web, mobile, or both?",
    "Do you need real-time sync or offline-first?"
  ],
  "next_stage": "intent_analysis"
}

​
Error (4xx / 5xx)

FieldDescription
status"error"
sessionId"" when no session.
stage"idea_input"
errorMessage.

​
Error Codes

HTTPCause
400idea missing, not a string, or empty after trim.
405Method not POST.
500processIdea (OpenRouter) or DB/write failure.

​
Implementation Notes

  • Uses processIdea(idea, sessionId) from lib/openai.ts (IdeaProcessor / OpenRouter).
  • Creates or updates Workflow via createWorkflowContextDB / updateWorkflowContextDB; falls back to in-memory in lib/x402 on DB errors.
  • Persists: idea, analysis, clarifyingQuestions, currentStage: 'idea_input'.