API Reference

StacksFinder REST API v1 documentation.

New to StacksFinder? Start with our Getting Started Guide to set up your account and create your first project.

---

Base URL

https://stacksfinder.com/api/v1

Development: http://localhost:5173/api/v1

---

Authentication

All endpoints (except /auth/register and /auth/login) require authentication via session cookie.

See Authentication Guide for details.

---

Response Format

All responses follow a consistent JSON format:

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human readable message",
  "details": [ ... ]  // Optional validation details
}

See Error Codes for the complete list.

---

Rate Limiting

Requests are rate-limited per user/IP:

Endpoint	Limit	Window
/auth/register	5 requests	1 hour
/auth/login	10 requests	15 minutes
/score	60 requests	1 minute
Other endpoints	100 requests	1 minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1703001600

---

Endpoints Overview

Authentication

Method	Endpoint	Description
POST	/auth/register	Create new account
POST	/auth/login	Login and get session
POST	/auth/logout	Invalidate session
GET	/auth/session	Get current user

Projects

Method	Endpoint	Description
GET	/projects	List user's projects
POST	/projects	Create new project
GET	/projects/:id	Get project details
DELETE	/projects/:id	Delete project
POST	/projects/:id/generate	Start blueprint generation

Blueprints

Method	Endpoint	Description
GET	/blueprints	List user's blueprints
GET	/blueprints/:id	Get blueprint details
DELETE	/blueprints/:id	Delete blueprint
GET	/blueprints/:id/exports	Export blueprint

Scoring

Method	Endpoint	Description
POST	/score	Real-time scoring (V2.1)

Document Analysis

Method	Endpoint	Description
POST	/analyze/upload	Upload document
GET	/analyze/:docId	Get document status
POST	/analyze/:docId/extract	Extract constraints
POST	/analyze/:docId/review	Submit review
POST	/analyze/:docId/generate	Generate from document

Jobs

Method	Endpoint	Description
GET	/jobs/:id	Get job status

Audits (NEW)

Method	Endpoint	Description	Scope
GET	/audits	List your audit reports	audit:read
POST	/audits	Create new audit report	audit:write
GET	/audits/:id	Get audit report	audit:read
DELETE	/audits/:id	Delete audit report	audit:write
POST	/audits/compare	Compare two audits	audit:read
GET	/audits/quota	Get audit quota status	audit:read

Demo

Method	Endpoint	Description
POST	/demo/capture	Capture demo email

---

OpenAPI Specification

The full OpenAPI 3.1 specification is available at:

• YAML: openapi.yaml
• Swagger UI: /api/docs (development only)

---

Versioning

The API uses URL versioning (/api/v1/). Breaking changes will increment the version number.

Current versions:

• API Version: v1
• Scoring Version: 2.1.0
• Tables Version: 1.0.0

Version information is included in scoring responses:

{
  "scoringVersion": "2.1.0",
  "tablesVersion": "1.0.0"
}

---

SDK & Tools

cURL Examples

# Login
curl -X POST https://stacksfinder.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret123"}' \
  -c cookies.txt

# Get projects (with session cookie)
curl https://stacksfinder.com/api/v1/projects \
  -b cookies.txt

JavaScript/TypeScript

// Using fetch
const response = await fetch("/api/v1/projects", {
  credentials: "include", // Include session cookie
});
const { projects } = await response.json();

---

Quick Links

• Authentication - Session management
• Audits - Technical debt audit API
• Error Codes - Error handling
• OpenAPI Spec - Full specification