Specflux API

SpecFlux API

Create and manage SpecFlux entities via REST API.

Prerequisites Check (REQUIRED)

Before making any API calls, check that required environment variables are set.

Run this check first:

echo "SPECFLUX_API_URL: ${SPECFLUX_API_URL:-NOT SET}"
echo "SPECFLUX_API_KEY: ${SPECFLUX_API_KEY:+SET (hidden)}"

If SPECFLUX_API_URL is NOT SET:

This is auto-injected when running inside SpecFlux app. If missing, either:

1. Restart the terminal from SpecFlux, or
2. Add to ~/.zshrc:

   export SPECFLUX_API_URL="http://localhost:8090"  # Local development
   

If SPECFLUX_API_KEY is NOT SET:

This requires manual setup. Add to ~/.zshrc:

export SPECFLUX_API_KEY="sfx_your_api_key_here"

Generate an API key from SpecFlux Settings > API Keys, then run source ~/.zshrc.

Do not proceed with API calls until both variables are set.

Making API Calls

Use $SPECFLUX_API_URL in all curl commands:

curl -H "Authorization: Bearer $SPECFLUX_API_KEY" "$SPECFLUX_API_URL/api/projects"

Core Workflows

Create PRD with Documents

# 1. Create PRD
POST /api/projects/{projectRef}/prds
{"title": "Authentication System", "description": "User auth with OAuth"}
# Returns: {"id": "prd_xxx", "displayKey": "PROJ-P1", "folderPath": ".specflux/prds/authentication-system", ...}

# 2. Add document to PRD
POST /api/projects/{projectRef}/prds/{prdRef}/documents
{"fileName": "prd.md", "filePath": ".specflux/prds/authentication-system/prd.md", "documentType": "PRD", "isPrimary": true}

# 3. Add supporting documents
POST /api/projects/{projectRef}/prds/{prdRef}/documents
{"fileName": "wireframe.png", "filePath": ".specflux/prds/authentication-system/wireframe.png", "documentType": "WIREFRAME"}

# 4. Update PRD status
PUT /api/projects/{projectRef}/prds/{prdRef}
{"status": "APPROVED"}

Create Epic with Tasks

IMPORTANT: When creating epics from a PRD, always include prdRef to link the epic back to its source PRD. This maintains traceability from requirements to implementation.

# 1. Create epic (linked to PRD) - prdRef and acceptanceCriteria are REQUIRED
POST /api/projects/{projectRef}/epics
{
  "title": "User Authentication",
  "description": "...",
  "prdRef": "PROJ-P1",           // REQUIRED - links epic to source PRD
  "releaseRef": "rel_xxx",       // Optional - assigns to a release
  "acceptanceCriteria": [        // REQUIRED - array of criteria objects
    {"criteria": "Users can sign up with email/password"},
    {"criteria": "Users can log in with existing credentials"}
  ]
}
# Returns: {"id": "epic_xxx", "displayKey": "PROJ-E1", "prdId": "prd_xxx", ...}

# 2. Add more acceptance criteria (optional)
POST /api/projects/{projectRef}/epics/{epicRef}/acceptance-criteria
{"criteria": "Password reset via email works"}

# 3. Create tasks
POST /api/projects/{projectRef}/tasks
{"epicRef": "epic_xxx", "title": "Database schema", "priority": "HIGH"}
# Returns: {"id": "task_xxx", "displayKey": "PROJ-42", ...}

# 4. Add task criteria
POST /api/projects/{projectRef}/tasks/{taskRef}/acceptance-criteria
{"criteria": "User table with id, email, password_hash, created_at"}

# 5. Add dependencies
POST /api/projects/{projectRef}/tasks/{taskRef}/dependencies
{"dependsOnTaskRef": "PROJ-41"}

CRITICAL FORMAT REQUIREMENTS:

• acceptanceCriteria MUST be an array of objects: [{"criteria": "..."}, {"criteria": "..."}]
• WRONG: ["string1", "string2"] - This will cause a 400 error
• CORRECT: [{"criteria": "string1"}, {"criteria": "string2"}]
• prdRef is required to link the epic to its source PRD (use display key like PROJ-P1 or internal ID)

Update Progress

# Mark criterion complete
PUT /api/projects/{projectRef}/tasks/{taskRef}/acceptance-criteria/{id}
{"isMet": true}

# Update task status
PATCH /api/projects/{projectRef}/tasks/{taskRef}
{"status": "COMPLETED"}

# Update epic status
PUT /api/projects/{projectRef}/epics/{epicRef}
{"status": "IN_PROGRESS"}

Read Entities

# Get task with criteria
GET /api/projects/{projectRef}/tasks/{taskRef}
GET /api/projects/{projectRef}/tasks/{taskRef}/acceptance-criteria

# Get epic with tasks
GET /api/projects/{projectRef}/epics/{epicRef}
GET /api/projects/{projectRef}/tasks?epicRef={epicRef}

Reference IDs

• projectRef: proj_xxx or project key like SPEC
• prdRef: prd_xxx or display key like SPEC-P1
• epicRef: epic_xxx or display key like SPEC-E1
• taskRef: task_xxx or display key like SPEC-42

Enums

PrdStatus: DRAFT, IN_REVIEW, APPROVED, ARCHIVED

PrdDocumentType: PRD, WIREFRAME, MOCKUP, DESIGN, OTHER

EpicStatus: PLANNING, IN_PROGRESS, BLOCKED, COMPLETED, CANCELLED

TaskStatus: BACKLOG, READY, IN_PROGRESS, IN_REVIEW, BLOCKED, COMPLETED, CANCELLED

TaskPriority: LOW, MEDIUM, HIGH, CRITICAL

Detailed Reference

See references/api.md for complete endpoint documentation with request/response schemas.