Skip to main content

​
API Reference Overview

Research Preview - This API is currently in research preview. Features and pricing are subject to change.

​
Base URL

https://api.pre.dev

​
Endpoints Overview

EndpointMethodPurposeAuth Required
/fast-specPOSTGenerate quick comprehensive spec✅
/deep-specPOSTGenerate ultra-detailed spec✅
/spec-status/:idGETCheck async generation status✅
/list-specsGETList all specs with pagination & filters✅
/find-specsGETSearch specs using regex patterns✅
/credits-balanceGETGet remaining prototype credits✅

​
Documentation Scraping

Both /fast-spec and /deep-spec endpoints support automatic documentation scraping and archival:
  • What it does: Scrapes external documentation URLs in parallel with spec generation
  • How to use: Provide docURLs array parameter with documentation URLs
  • What you get: Downloadable ZIP archives organized by platform
  • Response field: zippedDocsUrls array with download links for each platform
  • Benefits: AI agents and developers have complete context during implementation
Example: 
{
  "input": "Build payment system with Stripe",
  "docURLs": ["https://stripe.com/docs/api"],
}
Response includes: 
{
  "codingAgentSpecUrl": "https://api.pre.dev/s/abc123",
  "zippedDocsUrls": [
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "https://api.pre.dev/s/xyz789"
    }
  ]
}
See Fast Spec and Deep Spec documentation for complete details.

​
Direct SOW Outputs

/fast-spec and /deep-spec return the Scope of Work inline and as URL endpoints:
  • codingAgentSpecJson / codingAgentSpecMarkdown: simplified outputs for AI coding tools (no hours/personas/roles)
  • humanSpecJson / humanSpecMarkdown: full outputs with hours, personas, and roles for stakeholder review
  • URL fields codingAgentSpecUrl and humanSpecUrl continue to deliver downloadable specs

​
Request Modes

​
Synchronous (Default)

Request waits for completion, returns spec immediately 
{
  "async": false
}

​
Asynchronous

Request returns immediately with request ID, poll for status 
{
  "async": true
}

​
Generation Costs

EndpointCostWhat You Pay For
Fast Spec~5-10 creditsCharged per-inference based on actual token usage
Deep Spec~10-50 creditsCharged per-inference based on actual token usage

​
What is a “Credit”?

A credit = one AI model inference call. Specs require multiple LLM calls for:
  • Architecture analysis
  • Feature breakdown
  • Milestone planning
  • Story generation
  • Risk assessment
Credits are charged based on actual usage during generation. Cost varies with the complexity of your spec request.

​
Credit Sources (Priority Order)

  1. Prototype Credits - Used first if available
  2. Daily Allocation - Based on subscription tier
  3. Rollover Credits - Unused daily credits (if applicable)
Check remaining credits: Solo users: Visit https://pre.dev/project/playground Enterprise users: Visit https://pre.dev/enterprise/dashboard?page=api

​
Rate Limits

​
Daily Limits by Tier

TierFast SpecDeep SpecNotes
Solo PremiumUnlimited*Unlimited**Subject to fair use
EnterpriseUnlimited*Unlimited**Subject to fair use

​
Fair Use Policy

  • Max 100 spec credits per day per user/org
  • Max 10 concurrent async requests
  • Rate: Max 1 request per 5 seconds
Exceeding limits returns 429 Too Many Requests.

​
Error Handling

​
HTTP Status Codes

CodeMeaningAction
200SuccessProcess response
400Bad RequestCheck request parameters
401UnauthorizedVerify API key
402Insufficient CreditsVisit dashboard to purchase more credits
403ForbiddenCheck subscription status
429Rate LimitedWait and retry
500Server ErrorContact support

​
Common Error Responses

Insufficient Credits: 
{
  "error": "Insufficient credits",
  "message": "You have insufficient credits to generate a spec. Please purchase more credits or upgrade your plan.",
  "generationsAvailable": 0
}
Invalid Input: 
{
  "error": "Invalid input",
  "message": "Please provide a valid input string describing your spec"
}
Authentication Failed: 
{
  "error": "Invalid enterprise API key",
  "message": "The provided enterprise API key is not valid"
}

​
Quick Start Examples

Fast Spec - New Project

curl -X POST https://api.pre.dev/fast-spec \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Build a SaaS project management tool"
  }'

Deep Spec - Complex System

curl -X POST https://api.pre.dev/deep-spec \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Build an enterprise healthcare platform"
  }'

​
Best Practices

​
Input Quality

  • Be specific about core features and requirements
  • Include business context and constraints
  • Mention technical preferences if any

​
Error Handling

  • Always check response status codes
  • Implement retry logic for rate limits
  • Handle insufficient credit errors gracefully

​
Cost Management

  • Use Fast Spec for MVPs and prototypes
  • Reserve Deep Spec for complex, mission-critical projects
  • Monitor your credit usage via your dashboard regularly

Next: Fast Spec Endpoint

Complete documentation for generating quick specifications.