4.3 — Generation endpoints

AI generation tasks (features, user stories, schema, etc.) run as long-lived background jobs. You submit a task, poll or subscribe for progress, and get the results saved into your project when it finishes.

If you want to trigger a regeneration from the web app, use the buttons there — they call these same endpoints under the hood. If you want to automate it (e.g. nightly regenerations, or programmatic onboarding), this is the API.

Triggering generation

Submit a task

POST /api/llm-tasks/submit
Content-Type: application/json

{
  "taskType": "features",
  "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sessionId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "modelId": "gpt-5-nano"
}

Response 200 OK:

{
  "sessionId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "status": "pending"
}

The endpoint returns immediately — generation runs asynchronously. Subscribe to progress (below) or poll for the result.

Task types

Model options

The modelId field selects which LLM to use. Available models depend on your subscription tier — current options span Anthropic, OpenAI, and Google. If you omit modelId, VibeMap picks the best model for the task type automatically.

Monitoring progress

Poll for status

GET /api/progress/s1a2b3c4-d5e6-7890-abcd-ef1234567890

Response 200 OK:

{
  "sessionId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "status": "processing",
  "progress_percentage": 65,
  "current_phase": "generating_features",
  "message": "Generating feature 4 of 6..."
}

Status lifecycle

pending --> processing --> completed
                      \-> error
                      \-> cancelled

Polling strategy

Poll every 1-2 seconds during active generation. Stop polling when status is completed, error, or cancelled. If you don't want to poll, subscribe to real-time updates instead — see below.

Real-time updates (Pusher)

As an alternative to polling, subscribe to Pusher channels for instant updates.

Channel and events

Subscribe to channel task-{sessionId} and listen for these events:

Example (JavaScript / TypeScript)

import Pusher from "pusher-js";

const pusher = new Pusher(process.env.NEXT_PUBLIC_PUSHER_KEY!, {
  cluster: process.env.NEXT_PUBLIC_PUSHER_CLUSTER!,
});

const channel = pusher.subscribe(`task-${sessionId}`);

channel.bind("task-update", (data: { progress_percentage: number; message: string }) => {
  console.log(`${data.progress_percentage}%: ${data.message}`);
});

channel.bind("task-complete", () => {
  console.log("Generation complete");
  channel.unbind_all();
  pusher.unsubscribe(`task-${sessionId}`);
});

channel.bind("task-error", (data: { error: string }) => {
  console.error("Generation failed:", data.error);
});

Cancelling a task

Cancel an in-progress task

POST /api/llm-tasks/cancel
Content-Type: application/json

{
  "sessionId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

Response 200 OK:

{
  "status": "cancelled"
}

Only tasks with pending or processing status can be cancelled. Cancelling a completed or failed task returns 400 Bad Request.

Where to go next

• Read or write entities → 4.2 — CRUD endpoints
• Use the friendlier MCP wrapper from your IDE → 5 — MCP server