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

# API Examples

> Example usage of Scriptonia’s workflow and project APIs: fetch/curl, common patterns, and practical usage.

## Overview

These examples show how to interact with Scriptonia’s APIs during a typical workflow: Idea → Intent → Platform → Payment → Execution → Completion.

Requests are shown using `fetch` and `curl`. Adjust headers, body, and URLs based on your environment.

***

## Common Patterns

* All APIs are JSON-based.
* sessionId is required to associate requests with a workflow.
* Most APIs are POST.
* Errors are returned as `{ error }` with an HTTP status code.
* Successful responses include `{ status: 'success', ... }`.

***

## Create / Update Workflow Context

### Start or update workflow session

**POST** `/api/workflow`

```
curl -X POST http://localhost:3000/api/workflow \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"example-session-1"}'
```

***

## Idea

### Submit an idea

**POST** `/api/idea`

```
curl -X POST http://localhost:3000/api/idea \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "example-session-1",
    "idea": "A task management app for remote teams"
  }'
```

**Response includes**

* analysis
* clarifyingQuestions

***

## Intent

### Submit intent answers

**POST** `/api/intent`

```
curl -X POST http://localhost:3000/api/intent \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "example-session-1",
    "answers": {
      "targetUsers": "Remote software teams",
      "mustHave": ["Tasks", "Due dates"],
      "niceToHave": ["Notifications"]
    }
  }'
```

**Response includes**

* refinedRequirements
* features
* audience
* techNotes

***

## Platform

### Select platform

**POST** `/api/platform`

```
curl -X POST http://localhost:3000/api/platform \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "example-session-1",
    "platform": "Web Application"
  }'
```

**Response includes**

* platformOptions
* cost
* timeline

***

## Payment

### Create checkout (card)

**POST** `/api/dodo/create-checkout`

```
curl -X POST http://localhost:3000/api/dodo/create-checkout \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "example-session-1",
    "platform": "Web Application"
  }'
```

**Response includes**

* checkout\_url

***

## Confirm payment (optional)

**POST** `/api/dodo/confirm-payment`

```
curl -X POST http://localhost:3000/api/dodo/confirm-payment \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "example-session-1",
    "platform": "Web Application"
  }'
```

***

## Execute

### Run execution

**POST** `/api/execute`

```
curl -X POST http://localhost:3000/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "example-session-1"
  }'
```

**Behavior**

* Loads workflow
* Validates payment
* Runs execution agents
* Generates ZIP output

***

## Completion

### Fetch completion summary

**GET** `/api/completion?sessionId=example-session-1`

```
curl http://localhost:3000/api/completion?sessionId=example-session-1
```

**Response includes**

* summary
* downloadUrl
* project metadata

***

## Error Handling

Common errors:

* Missing sessionId
* Invalid workflow stage
* Payment not completed
* Execution already run

Errors are returned as:

```
{
  "error": "Description of the error"
}
```

***

## Notes

* Run APIs in order: Idea → Intent → Platform → Payment → Execute.
* Execution requires refinedRequirements to exist.
* Payment APIs may be skipped in test environments depending on configuration.