pulse-editor

---
name: Pulse Editor Vibe Dev Flow
description: Generate and build Pulse Apps using the Vibe Dev Flow API. Use this skill when the user wants to create, update, or generate code for Pulse Editor applications.
---

## Overview

This skill enables you to interact with the Pulse Editor Vibe Dev Flow API to generate, build, and publish Pulse Apps using cloud-based AI coding agents. The API uses Server-Sent Events (SSE) streaming to provide real-time progress updates.

## Why Use This Skill

This skill provides significant advantages for AI agents:

- **No Local Code Generation Required**: Instead of generating code locally on the user's machine, agents can offload code generation to Pulse Editor's cloud-based vibe coding service. This eliminates the need for local build tools, dependencies, or development environments.

- **Built-in Version Control**: Every app generation is automatically versioned. Agents can update existing apps by specifying `appId` and `version`, making it easy to iterate on applications without manual version management.

- **Instant Deployment**: Apps are automatically built and published immediately after generation. No separate build or deploy steps needed—users get a live, working app URL as soon as generation completes.

- **Parallel App Generation**: Agents can generate multiple apps simultaneously by making concurrent API calls. This is ideal for scenarios where an agent needs to scaffold several microservices, create multiple related applications, or batch-generate apps for different purposes—all at the same time.

- **Stateless & Scalable**: Since all code generation happens in the cloud, agents remain lightweight and can scale horizontally without worrying about local resource constraints.

## Important: Long-Running Task

**This API call is a long-running operation.** The Vibe Dev Flow performs multiple steps including workspace creation, AI code generation, building, and publishing. 

- **Expected duration**: Typically 2-5 minutes, but complex apps may take longer
- **Timeout threshold**: Do NOT time out the request unless it exceeds **10 minutes**
- **SSE streaming**: The connection stays open throughout the process. **Even if no SSE messages are received for a period, the request is NOT stalled or stuck as long as the connection remains open.** Wait for the stream to end or the 10-minute timeout.
- **Token efficiency**: Agents should use `"streamUpdatePolicy": "artifactOnly"` in the request body to receive only the final artifact output, significantly reducing input tokens. But it won't count as being stuck if no messages are received for a while.

## When to Use This Skill

Use this skill when the user wants to:

- Create a new Pulse App from a description or prompt
- Update an existing Pulse App with new features
- Generate code for a Pulse Editor application
- Build and publish a Pulse App

## API Authentication

The Pulse Editor API requires an API key for authentication. Users can obtain their API key by:

1. Signing up or logging in at https://pulse-editor.com/
2. Going to the **developer** section under account settings
3. Requesting beta access at https://pulse-editor.com/beta (if needed)
4. Creating and copying the API key from the developer section

The API key should be passed in the `Authorization` header as a Bearer token:

```
Authorization: Bearer your_api_key_here
```

## API Endpoint

**POST** `https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate`

### Request Headers

| Header          | Required | Description                            |
| --------------- | -------- | -------------------------------------- |
| `Authorization` | Yes      | Bearer token with Pulse Editor API key |
| `Content-Type`  | Yes      | `application/json`                     |
| `Accept`        | Yes      | `text/event-stream`                    |

### Request Body Parameters

| Parameter | Type   | Required | Description                                                                                | Example                                       |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------ | --------------------------------------------- |
| `prompt`  | string | Yes      | The user prompt instructing the Vibe coding agent                                          | `"Create a todo app with auth and dark mode"` |
| `appName` | string | No       | Friendly display name for the app                                                          | `"My Todo App"`                               |
| `appId`   | string | No       | Unique identifier of an existing app to update. If not provided, a new app will be created | `"my_app_x7k9q2"`                             |
| `version` | string | No       | Version identifier of an existing app. If not provided, defaults to latest version         | `"0.0.1"`                                     |
| `streamUpdatePolicy` | string | No | Set to `"artifactOnly"` to receive only the final artifact output (recommended for agents to save tokens) | `"artifactOnly"` |

### Response

The response is a Server-Sent Events (SSE) stream. Each event contains a JSON-encoded message. Messages are separated by `\n\n`.

Each SSE message is formatted as:

```
data: <JSON>
```

followed by a blank line.

#### Message Types

There are two message types:

**Creation Message** - A new message in the stream:

```json
{
  "messageId": "msg_abc123",
  "type": "creation",
  "data": {
    "type": "text" | "toolCall" | "toolResult" | "artifactOutput",
    "result": "string content",
    "error": "error message if any"
  },
  "isFinal": false
}
```

**Update Message** - Delta update to an existing message:

```json
{
  "messageId": "msg_abc123",
  "type": "update",
  "delta": {
    "result": "additional content to append",
    "error": "additional error to append"
  },
  "isFinal": true
}
```

#### Data Types

| Type              | Description                            |
| ----------------- | -------------------------------------- |
| `text`            | Text output from the agent             |
| `toolCall`       | Tool invocation by the agent           |
| `toolResult`     | Result from a tool execution           |
| `artifactOutput` | Final artifact with published app info |

#### Artifact Output Format

When the generation completes, an `artifactOutput` message contains:

```json
{
  "publishedAppLink": "https://pulse-editor.com/app/...",
  "sourceCodeArchiveLink": "https://...",
  "appId": "my_app_x7k9q2",
  "version": "0.0.1"
}
```

### Response Status Codes

| Code | Description                                  |
| ---- | -------------------------------------------- |
| 200  | Streaming SSE with progress and final result |
| 400  | Bad request - invalid parameters             |
| 401  | Unauthorized - invalid or missing API key    |
| 500  | Server error                                 |

## Example Usage

### cURL Example

```bash
curl -L 'https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'Authorization: Bearer your_api_key_here' \
  -d '{
    "prompt": "Create a todo app with auth and dark mode",
    "appName": "My Todo App"
  }'
```

### Python Example

```python
import requests
import json

url = "https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate"

headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json",
    "Accept": "text/event-stream"
}

payload = {
    "prompt": "Create a todo app with auth and dark mode",
    "appName": "My Todo App"
}

response = requests.post(url, json=payload, headers=headers, stream=True)

messages = {}  # Track messages by messageId
buffer = ""

for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
    buffer += chunk

    # SSE messages end with \n\n
    while "\n\n" in buffer:
        part, buffer = buffer.split("\n\n", 1)

        if not part.startswith("data:"):
            continue

        data = json.loads(part.replace("data: ", "", 1))

        if data["type"] == "creation":
            messages[data["messageId"]] = data
            print(f"New: {data['data'].get('result', '')}")

        elif data["type"] == "update":
            msg = messages.get(data["messageId"])
            if msg:
                msg["data"]["result"] = (msg["data"].get("result") or "") + (data["delta"].get("result") or "")
                msg["isFinal"] = data["isFinal"]

        # Check for artifact output
        if data.get("data", {}).get("type") == "artifactOutput" and data.get("isFinal"):
            result = json.loads(messages[data["messageId"]]["data"]["result"])
            print(f"Published: {result.get('publishedAppLink')}")
```

### JavaScript/Node.js Example

```javascript
const response = await fetch(
  "https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Create a todo app with auth and dark mode",
      appName: "My Todo App",
    }),
  },
);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
const messages = new Map();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });

  // SSE messages end with \n\n
  const parts = buffer.split("\n\n");
  buffer = parts.pop(); // Keep incomplete part in buffer

  for (const pa

... (truncated)