POST /fast-spec
Generate a quick, comprehensive project specification.Overview
- Cost: 10 credits
- Use Cases: MVPs, prototypes, rapid iteration
- Processing Time: ~30-40 seconds (sync) or instant return (async)
- Output: Complete feature breakdown, architecture, milestones
Endpoint
Headers
For JSON requests:Request Body
Parameters
For JSON requests:Parameter | Type | Required | Description |
---|---|---|---|
input | string | ✅ | Description of what you want to build |
outputFormat | string | ❌ | "url" (default) - returns hosted URL, or "markdown" - returns raw markdown in response |
currentContext | string | ❌ | CRITICAL: Existing project/codebase context. When provided, generates feature addition spec. When omitted, generates full new project spec with setup, deployment, docs, maintenance |
docURLs | string[] | ❌ | Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs |
async | boolean | ❌ | false (default) - wait for completion, or true - return immediately with requestId for status polling |
Parameter | Type | Required | Description |
---|---|---|---|
file | File | ❌ | Optional: File to be parsed as input (e.g., existing code, documentation, requirements). Can be used alone or combined with input text |
input | string | ❌ | Optional: Additional text description when using file upload. Can be empty string if using only file |
outputFormat | string | ❌ | "url" (default) - returns hosted URL, or "markdown" - returns raw markdown in response |
docURLs | string[] | ❌ | Optional: Array of documentation URLs that Architect will reference when generating specifications. Useful for API documentation, design systems, or existing project docs |
async | boolean | ❌ | false (default) - wait for completion, or true - return immediately with requestId for status polling |
Understanding currentContext
Omit currentContext
(New Project):
- Initial setup and scaffolding
- Deployment configuration
- Documentation structure
- Support and maintenance guidelines
- Infrastructure setup
- CI/CD pipelines
- Monitoring and logging
currentContext
(Feature Addition):
- New features only (respects existing architecture)
- Integration points with current codebase
- Migration considerations
- No redundant setup/deployment (already exists)
Example: New Project
Example: Feature Addition
Example: Async Request
Example: With Documentation URLs
Example: With File Upload
Example: File Upload with Additional Context
Response
Success Response (Sync Mode)
Field | Type | Description |
---|---|---|
endpoint | string | Endpoint used: "fast_spec" or "deep_spec" |
input | string | Original input text provided |
status | string | Completion status: "completed" when successful |
success | boolean | Whether the request succeeded |
output | any | Primary output - the hosted spec URL or markdown content |
outputFormat | string | Format used: "url" or "markdown" |
outputFileUrl | string | URL where the spec file is hosted (downloadable markdown) |
executionTime | number | Processing time in milliseconds |
predevUrl | string | pre.dev project URL where you can view and edit the spec |
lovableUrl | string | Deep link to Lovable.dev with auto-submit prompt to implement the spec |
cursorUrl | string | Deep link to Cursor with prompt to download and implement the spec |
v0Url | string | Deep link to Vercel v0 with prompt to implement the spec |
boltUrl | string | Deep link to Bolt.new with prompt to implement the spec |
outputFormat: "markdown"
:
Success Response (Async Mode)
Immediate response whenasync: true
:
Field | Type | Description |
---|---|---|
specId | string | Unique ID to poll for status (use with /api/spec-status/:specId ) |
status | string | Initial status: "pending" |
/api/spec-status/:specId
to check progress.
Async Status Flow
- Pending → Initial queue state
- Processing → Actively generating spec
- Completed → Success, output available
- Failed → Error occurred
- Fast Spec: 30-40 seconds
- Deep Spec: 2-3 minutes
Output Structure: Milestones → Stories
Fast Spec follows a two-level hierarchy optimized for rapid development:- ✅ High-level milestones group related features
- ✅ User stories with acceptance criteria
- ✅ Complexity estimates (XS, S, M, L, XL)
- ❌ No granular implementation subtasks
Code Examples
cURL - Complete Flow
Synchronous Request:Python - Complete Implementation
JavaScript/Node.js - Complete Implementation
TypeScript - Type-Safe Implementation
What You Get
The generated specification includes:- ✅ Executive summary
- ✅ Feature breakdown by category
- ✅ Technical architecture recommendations
- ✅ Implementation milestones with effort estimates
- ✅ User stories and acceptance criteria
- ✅ Task checklist with progress tracking
- Task status legend:
[ ]
→[→]
→[✓]
→[⊘]
- Update as your agent completes work
- Keep both you and AI aligned on progress
- Task status legend:
- ✅ Risk analysis and considerations
- ✅ Markdown formatted for direct agent use
Using Task Tracking
As your agent implements features, actively manage progress:- Mark tasks in progress: Change
[ ]
to[→]
when starting - Mark complete: Change
[→]
to[✓]
when done - Mark skipped: Change
[ ]
to[⊘]
if skipping (with reason)
Best Practices
Writing Effective Input
- Be specific about core features
- Include business context and constraints
- Mention technical preferences if any
Managing Your Agent
- Actively interrupt to ensure tasks are checked off
- Question every skipped task
- Verify acceptance criteria before marking complete
- Triple check that tests are written
Next: Deep Spec Endpoint
Authorizations
API key for authentication. Get your API key from https://pre.dev/projects/playground (Solo) or https://pre.dev/enterprise/dashboard?page=api (Enterprise). Use format: Bearer YOUR_API_KEY
Body
Description of what you want to build or the feature you want to add
"Build a SaaS project management tool with team collaboration and real-time updates"
Output format: 'url' returns a hosted URL (default), 'markdown' returns raw markdown content
url
, markdown
CRITICAL: Existing project/codebase context. When provided, generates feature addition spec. When omitted, generates full new project spec with setup, deployment, docs, maintenance
"Existing Next.js app with Supabase, has auth, task CRUD, team features"
Optional array of documentation URLs that Architect will reference when generating specifications
[
"https://docs.pre.dev",
"https://docs.stripe.com"
]
If true, returns immediately with requestId for status polling. If false (default), waits for completion
Response
Specification generated successfully
- Option 1
- Option 2
Which endpoint was used
fast_spec
, deep_spec
Original input text provided
Completion status
completed
Whether the request succeeded
Primary output - the hosted spec URL or markdown content
Format used
url
, markdown
URL where the spec file is hosted (downloadable markdown)
Processing time in milliseconds
pre.dev project URL where you can view and edit the spec
Deep link to Lovable.dev with auto-submit prompt to implement the spec
Deep link to Cursor with prompt to download and implement the spec
Deep link to Vercel v0 with prompt to implement the spec
Deep link to Bolt.new with prompt to implement the spec