> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scriptonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Idea API

> POST /api/idea — Submit an idea and receive analysis and clarifying questions.

## Endpoint

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

***

## Request Format

| Field       | Type   | Required | Description                                                     |
| :---------- | :----- | :------- | :-------------------------------------------------------------- |
| `idea`      | string | Yes      | User’s project idea (non-empty).                                |
| `sessionId` | string | No       | Existing 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)

| Field                  | Type                | Description                                                    |
| :--------------------- | :------------------ | :------------------------------------------------------------- |
| `status`               | `"success"`         |                                                                |
| `sessionId`            | string              | ID to use for subsequent intent, platform, payment, execute.   |
| `stage`                | `"idea_input"`      |                                                                |
| `analysis`             | object              | `summary`, `key_features[]`, `complexity`, `estimated_agents`. |
| `clarifying_questions` | string\[]           | 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)

| Field       | Description           |
| :---------- | :-------------------- |
| `status`    | `"error"`             |
| `sessionId` | `""` when no session. |
| `stage`     | `"idea_input"`        |
| `error`     | Message.              |

***

## Error Codes

| HTTP | Cause                                              |
| :--- | :------------------------------------------------- |
| 400  | `idea` missing, not a string, or empty after trim. |
| 405  | Method not POST.                                   |
| 500  | `processIdea` (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'`.

***