> ## 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.

# Intent API

>  POST /api/intent — Submit answers to clarifying questions and receive refined requirements.

## Endpoint

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

***

## Request Format

| Field       | Type      | Required | Description                                                      |
| :---------- | :-------- | :------- | :--------------------------------------------------------------- |
| `sessionId` | string    | Yes      | From `/api/idea` response.                                       |
| `answers`   | string\[] | Yes      | Answers to `clarifying_questions` (order preserved).             |
| `idea`      | string    | No       | Fallback if workflow context was lost; used to recreate context. |

### Example

```
{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "answers": [
    "Web and mobile, web first",
    "Real-time sync with offline support"
  ]
}
```

***

## Response Format

### Success (200)

| Field                  | Type                   | Description                                                                          |
| :--------------------- | :--------------------- | :----------------------------------------------------------------------------------- |
| `status`               | `"success"`            |                                                                                      |
| `stage`                | `"intent_analysis"`    |                                                                                      |
| `refined_requirements` | object                 | `title`, `description`, `features[]`, `target_audience`, `technical_requirements[]`. |
| `next_stage`           | `"platform_selection"` |                                                                                      |

### Example

```
{
  "status": "success",
  "stage": "intent_analysis",
  "refined_requirements": {
    "title": "Remote Team Task Manager",
    "description": "Kanban and time tracking for distributed teams with real-time sync.",
    "features": ["kanban", "time tracking", "real-time sync", "offline support"],
    "target_audience": "Remote and hybrid teams",
    "technical_requirements": ["Web (React/Next.js) first", "Mobile later", "Real-time backend"]
  },
  "next_stage": "platform_selection"
}
```

***

### Error (4xx / 5xx)

| Field    | Description         |
| :------- | :------------------ |
| `status` | `"error"`           |
| `stage`  | `"intent_analysis"` |
| `error`  | Message.            |

***

## Error Codes

| HTTP | Cause                                                                                                    |
| :--- | :------------------------------------------------------------------------------------------------------- |
| 400  | `sessionId` missing; `answers` missing, not array, or empty; context not found and no `idea` to recover. |
| 405  | Method not POST.                                                                                         |
| 500  | `refineIntent` (OpenRouter) or DB/write failure.                                                         |

***

## Implementation Notes

* Uses `getWorkflowContextDB` (then `getWorkflowContext`) to load context. If missing and `idea` is provided, creates/updates context with `idea` and then continues.
* Calls `refineIntent(idea, answers, sessionId)` from `lib/openai.ts` (IntentAnalyzer).
* Persists: `answers`, `refinedRequirements`, `currentStage: 'intent_analysis'`.

***