Validation Journey API

Import business models and assumptions from external tools and run validation journeys.

1Quick Start

Create a new validation journey by posting your business model. Assumptions will be auto-extracted by AI.

curl -X POST /api/journey \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Startup Idea",
    "problemStatement": "Small businesses struggle to manage inventory",
    "customerSegments": ["Retail store owners", "E-commerce sellers"],
    "valueProposition": "AI-powered inventory prediction",
    "solution": "Dashboard with demand forecasting",
    "channels": ["Direct sales", "App marketplaces"],
    "revenueStreams": ["Monthly subscription"],
    "externalId": "your-system-id-123"
  }'

API Endpoints

POST/api/journey

Create a new validation journey from a business model.

Request Body

{
  "name": string,              // Required: Journey name
  "problemStatement": string,  // The problem you're solving
  "customerSegments": string[],
  "valueProposition": string,
  "solution": string,
  "channels": string[],
  "revenueStreams": string[],
  "costStructure": string[],
  "keyMetrics": string[],
  "unfairAdvantage": string,
  "jobsToBeDone": string[],    // Optional: JTBD elements
  "pains": string[],
  "gains": string[],
  
  // Optional: Pre-defined assumptions (if not provided, AI extracts them)
  "assumptions": [{
    "text": string,
    "category": "Problem" | "Customer" | "Solution" | "Channel" | "Revenue" | "Cost" | "Other",
    "riskLevel": "Critical" | "High" | "Medium" | "Low",
    "stage": "Opportunity" | "Solution" | "Business Model" | "Scale"
  }],
  
  "externalId": string,       // Optional: Your system's ID for linking
  "webhookUrl": string        // Optional: URL for status updates
}

Response

{
  "success": true,
  "journey": {
    "id": "journey-xxx",
    "url": "/journey?id=journey-xxx",
    "endpoints": {
      "get": "/api/journey/journey-xxx",
      "iterations": "/api/journey/journey-xxx/iterations"
    },
    "assumptionsSummary": {
      "total": 12,
      "byStage": { "opportunity": 4, "solution": 3, ... },
      "byRisk": { "critical": 2, "high": 5, ... }
    },
    "opportunityAssumptions": [...]
  }
}

GET/api/journey

List all validation journeys.

GET/api/journey/:id

Get full details of a specific journey including model, assumptions, and iterations.

POST/api/journey/:id/iterations

Start a new test iteration. AI will plan experiments for the selected assumptions.

Request Body

{
  "targetAssumptionIds": ["assumption-1", "assumption-3"]
}

PATCH/api/journey/:id/iterations/:iterationId

Update experiment results within an iteration.

Request Body

{
  "status": "running",
  "experimentUpdates": [{
    "experimentId": "exp-xxx",
    "status": "completed",
    "actuals": [
      { "metric": "Response Rate", "actual": "15%", "passed": true }
    ],
    "outcome": "pass",
    "learnings": "Customers showed strong interest...",
    "evidence": "https://link-to-survey-results"
  }]
}

POST/api/journey/:id/iterations/:iterationId/complete

Complete an iteration and get AI decision (Kill/Pivot/Tweak/Continue). All experiments must be completed first.

Response

{
  "success": true,
  "decision": {
    "type": "Pivot",
    "confidence": "High",
    "reasoning": "Problem validated but current customer segment too small...",
    "pivotType": "Customer",
    "pivotDescription": "Target mid-market instead of small business",
    "nextSteps": ["Redefine ICP", "Update value prop messaging", ...],
    "risksToWatch": ["Longer sales cycles", "Higher CAC"]
  },
  "assumptionUpdates": [...],
  "modelChanges": [...],
  "journeyStatus": "pivoted",
  "currentPhase": "opportunity",
  "newVersion": { ... }
}

Complete Workflow Example

1
Import your model
POST to /api/journey with your business model. Get back journey ID and extracted assumptions.
2
Start an iteration
POST to /api/journey/:id/iterations with opportunity assumptions first. AI plans experiments.
3
Run experiments and record results
PATCH to /api/journey/:id/iterations/:iterationId with experiment outcomes.
4
Complete iteration and get decision
POST to /api/journey/:id/iterations/:iterationId/complete. AI recommends Kill/Pivot/Tweak/Continue.
5
Repeat or advance
Based on decision, either pivot/tweak model or advance to next phase (Solution, Business Model, Scale).

Journey Statuses

active

Journey is in progress

pivoted

Model has been pivoted, continue testing

validated

All phases validated successfully

killed

Idea invalidated, do not proceed

View journeys in the UI at /journey