POST https://api.pre.dev/fast-spec

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

{
  "input": "Build a task management SaaS"
}

{
  "input": "Add real-time notifications and activity feed",
  "currentContext": "Existing Next.js task management app with Supabase, has auth, task CRUD, team features"
}

{
  "input": "Build a SaaS project management tool with team collaboration, real-time updates, task tracking, and time logging. Include user authentication and role-based permissions.",
}

{
  "input": "Add a calendar view and Gantt chart visualization to the existing project management tool",
  "currentContext": "We have a task management system with list and board views, user auth, and basic team features",
}

{
  "input": "Build a comprehensive e-commerce platform with inventory management",
  "async": true
}

{
  "input": "Build a customer support ticketing system with priority levels and file attachments",
  "docURLs": [
    "https://docs.pre.dev",
    "https://docs.stripe.com"
  ]
}

// Prepare file upload
const formData = new FormData();
formData.append('file', fileInput.files[0]); // fileInput is your HTML file input
formData.append('input', '');
formData.append('docURLs', JSON.stringify(["https://docs.pre.dev"]));

const response = await fetch('http://localhost:3001/fast-spec', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

// Upload a requirements document and add context
const formData = new FormData();
formData.append('file', requirementsFile); // PDF or text file with requirements
formData.append('input', 'Please focus on the authentication and user management features from the uploaded requirements document');
formData.append('docURLs', JSON.stringify(["https://docs.pre.dev/auth"]));

{
  "endpoint": "fast_spec",
  "input": "Build a SaaS project management tool with team collaboration...",
  "status": "completed",
  "success": true,
  "humanSpecUrl": "https://api.pre.dev/s/a6hFJRV6",
  "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV7",
  "codingAgentSpecJson": {
    "executiveSummary": "A modern task management platform...",
    "coreFunctionalities": [
      { "name": "Task CRUD", "description": "Create, read, update, delete tasks", "priority": "High" }
    ],
    "techStack": [
      { "name": "React", "category": "Frontend" },
      { "name": "Node.js", "category": "Backend" }
    ],
    "techStackGrouped": { "Frontend": ["React", "TailwindCSS"], "Backend": ["Node.js", "Express"] },
    "milestones": [
      {
        "milestoneNumber": 1,
        "description": "Core Task Management",
        "stories": [
          {
            "id": "US-001",
            "title": "User can create a task",
            "acceptanceCriteria": ["Task form validates input", "Task saved to database"],
            "complexity": "M",
            "subTasks": [{ "id": "ST-001", "description": "Design task form UI", "complexity": "S" }]
          }
        ]
      }
    ]
  },
  "codingAgentSpecMarkdown": "# Task Management App\\n\\n## Executive Summary\\n...",
  "humanSpecJson": {
    "executiveSummary": "A modern task management platform...",
    "personas": [{ "title": "Team Lead", "description": "Manages work allocation" }],
    "techStack": [{ "name": "PostgreSQL", "category": "Database" }],
    "techStackGrouped": { "Database": ["PostgreSQL"] },
    "roles": [{ "name": "Full Stack Developer", "shortHand": "FSD" }],
    "totalHours": 120,
    "milestones": [
      {
        "milestoneNumber": 1,
        "description": "Core Task Management",
        "hours": 40,
        "stories": [
          {
            "id": "US-001",
            "title": "User can create a task",
            "hours": 8,
            "subTasks": [{ "description": "Implement task creation API", "hours": 3, "complexity": "M" }]
          }
        ]
      }
    ]
  },
  "humanSpecMarkdown": "# Task Management App\\n\\n## Executive Summary\\n...",
  "architectureInfographicUrl": "https://res.cloudinary.com/dfvg7gm6w/image/upload/v1765403270/infographics/arch_infographic_cfac141b_1765403269989_0.jpg",
  "executionTime": 38500,
  "predevUrl": "https://pre.dev/projects/abc123",
  "creditsUsed": 7,
  "zippedDocsUrls": [
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "https://api.pre.dev/s/xyz789"
    },
    {
      "platform": "docs.github.com",
      "masterZipShortUrl": "https://api.pre.dev/s/abc456"
    }
  ]
}

{
  "specId": "507f1f77bcf86cd799439011",
  "status": "pending"
}

### - [ ] **Milestone 1**: User authentication and profile management

- [ ] **User Registration** - (M): As a: new user, I want to: register an account with email and password, So that: I can access the platform
  - **Acceptance Criteria:**
    - [ ] User can register with valid email and password
    - [ ] Email verification sent upon registration
    - [ ] Duplicate emails handled gracefully
    - [ ] Password strength requirements enforced

- [ ] **User Login** - (S): As a: registered user, I want to: log in securely, So that: I can access my account
  - **Acceptance Criteria:**
    - [ ] User can log in with correct credentials
    - [ ] Invalid credentials rejected with clear message
    - [ ] Session persists across browser tabs
    - [ ] Password reset option available

- [ ] **User Profile** - (M): As a: registered user, I want to: manage my profile, So that: I can update my information
  - **Acceptance Criteria:**
    - [ ] User can view and edit profile details
    - [ ] Shipping addresses can be saved
    - [ ] Password can be changed with re-authentication
    - [ ] Account can be deactivated

interface CodingAgentSpecJson {
  title?: string;
  executiveSummary: string;
  coreFunctionalities: SpecCoreFunctionality[];
  techStack: SpecTechStackItem[];
  techStackGrouped: Record<string, string[]>;
  milestones: CodingAgentMilestone[];
}

interface CodingAgentMilestone {
  milestoneNumber: number;
  description: string;
  stories: CodingAgentStory[];
}

interface CodingAgentStory {
  id?: string;
  title: string;
  description?: string;
  acceptanceCriteria?: string[];
  complexity?: string;
  subTasks: CodingAgentSubTask[];
}

interface CodingAgentSubTask {
  id?: string;
  description: string;
  complexity: string; // "S" | "M" | "L" | "XL"
}

interface HumanSpecJson {
  title?: string;
  executiveSummary: string;
  coreFunctionalities: SpecCoreFunctionality[];
  personas: SpecPersona[];
  techStack: SpecTechStackItem[];
  techStackGrouped: Record<string, string[]>;
  milestones: HumanSpecMilestone[];
  totalHours: number;
  roles: SpecRole[];
}

interface HumanSpecMilestone {
  milestoneNumber: number;
  description: string;
  hours: number;
  stories: HumanSpecStory[];
}

interface HumanSpecStory {
  id?: string;
  title: string;
  description?: string;
  acceptanceCriteria?: string[];
  hours: number;
  complexity?: string;
  subTasks: HumanSpecSubTask[];
}

interface HumanSpecSubTask {
  id?: string;
  description: string;
  hours: number;
  complexity: string;
  roles?: SpecRole[];
}

interface SpecPersona {
  title: string;
  description: string;
  primaryGoals?: string[];
  painPoints?: string[];
  keyTasks?: string[];
}

interface SpecRole {
  name: string;
  shortHand: string;
}

interface SpecCoreFunctionality {
  name: string;
  description: string;
  priority?: string; // "High" | "Medium" | "Low"
}

interface SpecTechStackItem {
  name: string;
  category: string;
}

curl -X POST https://api.pre.dev/fast-spec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "input": "Build a real-time collaborative whiteboard with drawing tools, shapes, text, and team presence indicators"
  }'

# Step 1: Start async processing
RESPONSE=$(curl -X POST https://api.pre.dev/fast-spec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "input": "Build a CRM with contact management, deal pipeline, and email integration",
    "async": true
  }')

SPEC_ID=$(echo $RESPONSE | jq -r '.specId')

# Step 2: Poll for status
while true; do
  STATUS=$(curl https://api.pre.dev/spec-status/$SPEC_ID \
    -H "Authorization: Bearer YOUR_API_KEY")

  STATE=$(echo $STATUS | jq -r '.status')

  if [ "$STATE" = "completed" ]; then
    echo "Spec ready!"
    echo $STATUS | jq -r '.codingAgentSpecUrl'
    break
  elif [ "$STATE" = "failed" ]; then
    echo "Processing failed"
    echo $STATUS | jq -r '.errorMessage'
    break
  fi

  echo "Status: $STATE - $(echo $STATUS | jq -r '.progress')"
  sleep 10
done

import requests
import time
from typing import Dict, Any

class ArchitectAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.pre.dev"

    def generate_spec(
        self,
        input_text: str,
        current_context: str = None,
        async_mode: bool = False
    ) -> Dict[str, Any]:
        """Generate a fast spec."""
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.api_key}"
        }

        payload = {
            "input": input_text,
            "async": async_mode
        }

        if current_context:
            payload["currentContext"] = current_context

        response = requests.post(
            f"{self.base_url}/fast-spec",
            headers=headers,
            json=payload
        )

        response.raise_for_status()
        return response.json()

    def check_status(self, spec_id: str) -> Dict[str, Any]:
        """Check async processing status."""
        headers = {"Authorization": f"Bearer {self.api_key}"}

        response = requests.get(
            f"{self.base_url}/spec-status/{spec_id}",
            headers=headers
        )

        response.raise_for_status()
        return response.json()

    def wait_for_completion(self, spec_id: str, poll_interval: int = 10) -> Dict[str, Any]:
        """Wait for async processing to complete."""
        while True:
            status = self.check_status(spec_id)

            if status["status"] == "completed":
                return status
            elif status["status"] == "failed":
                raise Exception(f"Processing failed: {status.get('errorMessage')}")

            print(f"Status: {status['status']} - {status.get('progress', 'Processing...')}")
            time.sleep(poll_interval)

# Usage
api = ArchitectAPI(api_key="YOUR_API_KEY")

# Synchronous (wait for result)
result = api.generate_spec(
    input_text="Build a fitness tracking app with workout logging, progress charts, and social features",
)
print(f"Spec URL: {result['codingAgentSpecUrl']}")

# Asynchronous (poll for result)
response = api.generate_spec(
    input_text="Add AI meal planning and nutrition tracking to existing fitness app",
    current_context="Existing app has workout logging, user profiles, and basic social features built with React Native and Firebase",
    async_mode=True
)

result = api.wait_for_completion(response["specId"])
print(f"Spec ready: {result['codingAgentSpecUrl']}")

const fetch = require('node-fetch');

class ArchitectAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.pre.dev';
  }

  async generateSpec({
    input,
    currentContext = null,
    async = false
  }) {
    const headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.apiKey}`
    };

    const payload = {
      input,
      async
    };

    if (currentContext) {
      payload.currentContext = currentContext;
    }

    const response = await fetch(`${this.baseUrl}/fast-spec`, {
      method: 'POST',
      headers,
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }

    return response.json();
  }

  async checkStatus(specId) {
    const headers = { 'Authorization': `Bearer ${this.apiKey}` };

    const response = await fetch(
      `${this.baseUrl}/spec-status/${specId}`,
      { headers }
    );

    if (!response.ok) {
      throw new Error('Failed to check status');
    }

    return response.json();
  }

  async waitForCompletion(specId, pollInterval = 10000) {
    while (true) {
      const status = await this.checkStatus(specId);

      if (status.status === 'completed') {
        return status;
      } else if (status.status === 'failed') {
        throw new Error(`Processing failed: ${status.errorMessage}`);
      }

      console.log(`Status: ${status.status} - ${status.progress || 'Processing...'}`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  }
}

// Usage Examples

// Synchronous
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    const result = await api.generateSpec({
      input: 'Build an e-learning platform with video courses, quizzes, certificates, and student progress tracking'
    });

    console.log('Spec URL:', result.codingAgentSpecUrl);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

// With Documentation URLs
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    const result = await api.generateSpec({
      input: 'Build a customer support ticketing system with priority levels and file attachments',
      docURLs: [
        'https://docs.pre.dev',
        'https://docs.stripe.com'
      ]
    });

    console.log('Spec URL:', result.codingAgentSpecUrl);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

// With File Upload
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    // For file uploads, use multipart/form-data
    const formData = new FormData();
    formData.append('file', fileInput.files[0]);
    formData.append('input', 'Analyze the uploaded requirements document');
    formData.append('docURLs', JSON.stringify(['https://docs.pre.dev']));

    const response = await fetch(`${api.baseUrl}/fast-spec`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${api.apiKey}`
        // Note: Don't set Content-Type for FormData - browser sets it automatically
      },
      body: formData
    });

    const result = await response.json();
    console.log('Spec URL:', result.codingAgentSpecUrl);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

// Asynchronous with polling
(async () => {
  const api = new ArchitectAPI('YOUR_API_KEY');

  try {
    // Start processing
    const response = await api.generateSpec({
      input: 'Add gamification with points, badges, and leaderboards',
      currentContext: 'Existing e-learning platform with courses and progress tracking',
      async: true
    });

    console.log('Spec ID:', response.specId);

    // Wait for completion
    const result = await api.waitForCompletion(response.specId);
    console.log('Spec ready:', result.codingAgentSpecUrl);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

interface SpecRequest {
  input: string;
  currentContext?: string;
  docURLs?: string[];
  async?: boolean;
}

interface FileUploadRequest {
  file?: File;
  input?: string;
  docURLs?: string[];
  async?: boolean;
}

interface SpecResponse {
  codingAgentSpecUrl?: string;
  markdown?: string;
  fileUrl: string;
}

interface AsyncResponse {
  specId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
}

interface ZippedDocsUrl {
  platform: string;
  masterZipShortUrl: string;
  masterMarkdownShortUrl?: string;
}

interface StatusResponse {
  _id?: string;
  created?: string;
  endpoint: 'fast_spec' | 'deep_spec';
  input: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  success: boolean;
  uploadedFileShortUrl?: string;
  uploadedFileName?: string;
  humanSpecUrl?: string;
  totalHumanHours?: number;
  architectureInfographicUrl?: string;
  codingAgentSpecUrl?: string;
  executionTime?: number;
  predevUrl?: string;
  zippedDocsUrls?: ZippedDocsUrl[];
  errorMessage?: string;
  creditsUsed?: number;     // Total credits consumed (available during processing and on completion)
  progress?: number;        // Overall progress percentage (0-100)
  progressMessage?: string; // Detailed progress message (e.g., "Generating User Stories...")
}

class ArchitectAPI {
  private apiKey: string;
  private baseUrl: string = 'https://api.pre.dev';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async generateSpec(request: SpecRequest): Promise<SpecResponse | AsyncResponse> {
    const response = await fetch(`${this.baseUrl}/fast-spec`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify(request)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }

    return response.json();
  }

  async checkStatus(specId: string): Promise<StatusResponse> {
    const response = await fetch(`${this.baseUrl}/spec-status/${specId}`, {
      headers: { 'Authorization': `Bearer ${this.apiKey}` }
    });

    if (!response.ok) {
      throw new Error('Failed to check status');
    }

    return response.json();
  }

  async waitForCompletion(specId: string, pollInterval: number = 10000): Promise<StatusResponse> {
    while (true) {
      const status = await this.checkStatus(specId);

      if (status.status === 'completed') {
        return status;
      } else if (status.status === 'failed') {
        throw new Error(`Processing failed: ${status.errorMessage}`);
      }

      console.log(`${status.status}: ${status.progress || 'Processing...'}`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  }
}

interface ZippedDocsUrl {
  platform: string;              // Hostname extracted from doc URL (e.g., "stripe.com", "docs.github.com")
  masterZipShortUrl: string;     // Short URL to download the ZIP archive
  masterMarkdownShortUrl?: string; // Optional: consolidated markdown file
}

{
  "input": "Build a payment processing system with Stripe integration",
  "docURLs": [
    "https://stripe.com/docs/api",
    "https://stripe.com/docs/payments",
    "https://docs.github.com/en/rest"
  ]
}

{
  "endpoint": "fast_spec",
  "codingAgentSpecUrl": "https://api.pre.dev/s/a6hFJRV6",
  "zippedDocsUrls": [
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "https://api.pre.dev/s/xyz789"
    },
    {
      "platform": "docs.github.com",
      "masterZipShortUrl": "https://api.pre.dev/s/abc456"
    }
  ]
}