Core Workflows

Standard API sequences for common VibeMap tasks.

Building a complete project plan involves navigating relationships between several entities. This guide outlines standard API sequences for common developer tasks.

1. Creating a Project from a Prompt

The most common workflow is initiating a new project analysis.

Step 1: POST to /crud/projects

Send your initial project description.

{
  "name": "E-commerce App",
  "original_prompt": "I want to build a marketplace for used books.",
  "current_prompt": "I want to build a marketplace for used books.",
  "model": "gpt-4o"
}

Tip: Save the returned id for subsequent steps.

Step 2: Poll for Analysis (Optional)

While project creation is instantaneous, background AI analysis (summary generation) might take a few seconds. You can fetch the project by ID with includeAnalysis=true to see if the summary fields have been populated.

---

2. Listing and Exporting Requirements

To build a requirement matrix or sync with an external tool:

Step 1: Fetch all Features

GET /crud/features?project_id=YOUR_PROJECT_ID

Step 2: Fetch User Stories per Feature

For each feature ID, you can fetch its associated stories: GET /crud/user-stories?feature_id=FEATURE_ID&includeCriteria=true

---

3. The Batch Migration Workflow

If you are importing requirements from an external source (like a spreadsheet or another project tool), use the Batch Create operations to avoid hitting rate limits.

Step 1: Batch Create Personas

POST /crud/personas

{
  "operation": "create",
  "personas": [
    { "data": { "project_id": "...", "name": "Admin", ... } },
    { "data": { "project_id": "...", "name": "Buyer", ... } }
  ]
}

Step 2: Batch Create Features

POST /crud/features ...using the same pattern as above.

---

4. Requirement Refining Workflow

As you refine your project, you might want to update the current_prompt and see how it affects downstream artifacts.

1. Update Project: PUT /crud/projects?id=... with a new current_prompt.

2. Verify Status: Check the updated_at timestamps on features and stories to ensure your sync service pulls the latest versions.

3. Clean up: Use DELETE /crud/features?id=... for any requirements that are now out of scope.