Documentation

curl -X POST https://api.cesaflow.ai/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "secret", "organization_name": "My Org"}'

# Response:
# { "api_key": "sk_...", "org_id": "..." }

curl -X POST https://api.cesaflow.ai/api/v1/runs \
  -H "x-api-key: sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective": "Build a FastAPI todo app with JWT auth", "project_id": "my-todo"}'

# Response:
# { "run_id": "abc-123", "status": "pending" }

# Poll for status
curl https://api.cesaflow.ai/api/v1/runs/abc-123 \
  -H "x-api-key: sk_YOUR_KEY"

# Or connect WebSocket for live events:
# wss://api.cesaflow.ai/ws/runs?api_key=sk_YOUR_KEY

# Download when done:
curl https://api.cesaflow.ai/api/v1/runs/abc-123/download \
  -H "x-api-key: sk_YOUR_KEY" -o workspace.zip

cd cli/
pip install -e .

# Or with pipx:
pipx install -e .

aios run "Build a REST API for a blog"
aios run "Add JWT auth" --project my-blog
aios run "Build a FastAPI app" --tasks backend,qa   # select agents
aios run "..." --model gpt-4o                       # override model

aios benchmark              # run all 10 tasks
aios benchmark --list      # list available tasks
aios benchmark --tasks hello_world,calculator  # run specific tasks

aios logs <run-id>          # stream events for a run
aios logs <run-id> --follow  # keep streaming until done

AIOS_API_KEY=sk_...      # your API key
AIOS_API_URL=https://api.cesaflow.ai  # API base URL (default)
OPENAI_API_KEY=sk_...   # for agents to call LLMs
GITHUB_TOKEN=ghp_...    # for git/PR tools (optional)
PLAYWRIGHT_ENABLED=1    # enable browser tool (optional)

Each task: 10 points max
Check types:
  file_exists       — does the required file exist?
  file_contains     — does it contain the expected code?
  any_file_contains — does any file contain the pattern?

Score = (passed_checks / total_checks) * 10
Grade: S (90+) · A (80+) · B (70+) · C (60+) · D (50+) · F (<50)

POST /api/v1/inline/edit
{ "code": "def hello():\n  print('hi')", "instruction": "Add type hints and docstring" }

Response: { "edited_code": "def hello() -> None:\n  \"\"\"Greet the user.\"\"\"\n  print('hi')", "summary": "Added return type and docstring" }

POST /api/v1/inline/chat
{ "file_context": "...", "message": "What does this function do?" }

Response: { "reply": "This function validates JWT tokens..." }

POST /api/v1/inline/complete
{ "prefix": "def calculate_tax(amount: float, ", "suffix": "):\n  return" }

Response: { "completion": "rate: float = 0.2" }

# Review a GitHub PR
POST /api/v1/review
{
  "github_url": "https://github.com/owner/repo/pull/123",
  "focus": "security",      // general | security | performance | style
  "language": "auto"
}

# Or review a raw diff
POST /api/v1/review
{
  "diff_content": "--- a/main.py\n+++ b/main.py\n@@ -1,3 +1,5 @@...",
  "focus": "general"
}

# Response: { "review_id": "abc123", "status": "processing" }

# Poll for results
GET /api/v1/review/abc123
# Returns: { "status": "completed", "result": "## Summary\n..." }

POST /api/v1/runs
{
  "objective": "Build a REST API for a blog",
  "project_id": "my-blog",
  "continuation": {
    "next_objective": "Add frontend with React for the blog API",
    "trigger_condition": "on_success",
    "max_depth": 3,
    "inherit_workspace": true,
    "then": {
      "next_objective": "Write E2E tests for the full-stack blog",
      "trigger_condition": "on_success"
    }
  }
}

# Flow:
# Run 1: Build API → completes → triggers Run 2
# Run 2: Build frontend → completes → triggers Run 3
# Run 3: Write tests → completes → chain done

# Track the chain:
GET /api/v1/runs/{run_id}/chain
# Returns all runs in order with status

GET /api/v1/runs/learning/stats

Response:
{
  "total_patterns": 23,
  "fixed_patterns": 18,
  "by_agent": {
    "backend": 12,
    "frontend": 8,
    "qa": 3
  },
  "top_errors": [
    { "type": "validation_failure", "count": 7, "agent": "backend" },
    { "type": "validation_failure", "count": 5, "agent": "frontend" }
  ]
}

POST /api/v1/runs/money/start
{
  "template_id": "saas_mvp",
  "customization": "Use React + Tailwind, target fitness industry"
}

# Response: { "run_id": "...", "template": "SaaS MVP", "revenue_model": "Subscription" }

# During a run, agents can call:
generate_deploy(platform="vercel", app_name="my-saas")

# This creates deployment files in the workspace:
# → vercel.json
# → .vercelignore

# Or for Docker:
generate_deploy(platform="docker", app_name="my-api")
# → Dockerfile
# → docker-compose.yml
# → .dockerignore

GET /api/v1/runs/clone/profile

Response:
{
  "status": "active",
  "runs_analyzed": 23,
  "preferred_stack": ["python", "typescript", "react"],
  "preferred_persona": "fullstack",
  "preferred_model": "claude-3-5-sonnet",
  "top_keywords": [
    { "word": "api", "count": 8 },
    { "word": "auth", "count": 5 }
  ],
  "profile_summary": "Primarily works with python, typescript, react. Prefers fullstack builds."
}

# Clone context is automatically injected into agent prompts:
GET /api/v1/runs/clone/context
# → "This user prefers: python, typescript. Default: fullstack. Adapt output accordingly."

POST /api/v1/runs/goal/start
{
  "goal": "Build a complete SaaS product for project management with auth, teams, tasks, billing, and deploy to Vercel",
  "project_id": "my-saas"
}

# CesaFlow:
# 1. Decomposes into 5 tasks:
#    → Build auth system with JWT
#    → Create team + task management API
#    → Build React frontend with dashboard
#    → Add Stripe billing integration
#    → Generate Vercel deploy config + tests
#
# 2. Chains them automatically
# 3. Each task validates before continuing
# 4. Self-corrects on failure
#
# Response: { "goal_id": "...", "run_id": "...", "tasks": [...], "total_steps": 5 }

GET /api/v1/runs/auto-config

# Returns optimal config based on your run history:
{
  "auto_optimized": true,
  "recommended_model": "claude-3-5-sonnet",
  "recommended_strategy": "balanced",
  "recommended_provider": "anthropic"
}

# CesaFlow analyzes your pass rate, cost trends, and model performance
# to automatically suggest the best configuration.

POST /api/v1/runs/modules/resolve
{ "modules": ["admin_panel", "rate_limiting"] }

# Response:
{
  "resolved": ["admin_panel", "rate_limiting", "auth_jwt"],
  "added": [{ "module": "auth_jwt", "required_by": "admin_panel" }],
  "conflicts": [],
  "total": 3
}
# auth_jwt auto-added because admin_panel depends on it

POST /api/v1/policies
{
  "name": "secure-production",
  "model_strategy": "balanced",
  "max_cost_usd": 5.0,
  "max_runtime_minutes": 30,
  "preferred_providers": ["anthropic", "openai", "groq"],
  "fallback_enabled": true,
  "blocked_commands": ["rm -rf", "sudo", "shutdown", "curl | bash"],
  "allowed_tools": ["write_file", "read_file", "run_command", "list_files"],
  "require_approval": true
}

POST /api/v1/runs
{
  "objective": "Build a payment API",
  "policy_id": "abc123"
}

# Enforcement:
# • Cost tracked per node — run stops if limit exceeded
# • Runtime checked per wave — remaining nodes skipped if timeout
# • Blocked commands rejected at execution time
# • Only allowed tools available to agents
# • PR creation pauses for human approval

# For each AI call, CesaFlow checks in this order:

1. User BYOM key (model_credentials table)
   → If found: use for ALL agents (planner + backend + frontend + qa)
   → User pays their provider directly

2. Admin Vault key (api_vault table) — only for allowed purposes
   → chat, planner, discussion, inline edit, review, estimate
   → NOT used for: backend, frontend, qa, devops agents
   → If no BYOM: backend/frontend/qa return "Add your own key" error

3. System config / env var (legacy fallback)
   → Same restrictions as vault

# Fallback within vault:
# Priority 10 (Groq) fails → try Priority 20 (Gemini) → Priority 30 (OpenAI)

GET /api/v1/runs/models/catalog

Response:
{
  "total_models": 38,
  "providers": [
    {
      "id": "groq",
      "name": "Groq",
      "model_count": 4,
      "models": [
        {
          "id": "llama-3.3-70b-versatile",
          "name": "Llama 3.3 70B",
          "context": 128000,
          "rate_limit": "30 req/min, 14400 tokens/min",
          "pricing": "Free",
          "best_for": "General, coding"
        },
        ...
      ]
    },
    ...
  ]
}

# Per-provider:
GET /api/v1/runs/models/catalog/openai
GET /api/v1/runs/models/catalog/anthropic