API Reference 🟡 BETA

Complete API reference for the AutoTask system. All endpoints require authentication.

Base URL

All endpoints are relative to your bot’s API base URL:

https://your-bot.example.com/api/autotask

Intent Classification

Classify Intent

Classify a natural language intent and optionally process it.

POST /api/autotask/classify

Request Body

Example Request

{
  "intent": "Create an app for my clinic with patients and appointments",
  "auto_process": true
}

Response

{
  "success": true,
  "intent_type": "APP_CREATE",
  "confidence": 0.92,
  "suggested_name": "clinic",
  "requires_clarification": false,
  "clarification_question": null,
  "result": {
    "success": true,
    "message": "Done:\npatients table created\nappointments table created\nApp available at /apps/clinic",
    "app_url": "/apps/clinic",
    "task_id": null,
    "schedule_id": null,
    "tool_triggers": [],
    "created_resources": [
      {"resource_type": "table", "name": "patients", "path": "tables.bas"},
      {"resource_type": "table", "name": "appointments", "path": "tables.bas"},
      {"resource_type": "page", "name": "Dashboard", "path": "index.html"}
    ],
    "next_steps": ["Open the app to start using it", "Use Designer to customize the app"]
  },
  "error": null
}

Intent Types

Intent Compilation

Compile Intent

Compile an intent into an execution plan without executing.

POST /api/autotask/compile

Request Body

Example Request

{
  "intent": "Create a CRM for tracking customers and orders",
  "execution_mode": "semi-automatic",
  "priority": "medium"
}

Response

{
  "success": true,
  "plan_id": "550e8400-e29b-41d4-a716-446655440000",
  "plan_name": "CRM Application",
  "plan_description": "Customer relationship management system",
  "steps": [
    {
      "id": "step-1",
      "order": 1,
      "name": "Create customers table",
      "description": "Define customer data structure",
      "keywords": ["TABLE"],
      "priority": "HIGH",
      "risk_level": "LOW",
      "estimated_minutes": 1,
      "requires_approval": false
    }
  ],
  "alternatives": [],
  "confidence": 0.85,
  "risk_level": "LOW",
  "estimated_duration_minutes": 5,
  "estimated_cost": 0.02,
  "resource_estimate": {
    "compute_hours": 0.1,
    "storage_gb": 0.01,
    "api_calls": 5,
    "llm_tokens": 2000,
    "estimated_cost_usd": 0.02
  },
  "basic_program": "' Generated BASIC program\nTABLE customers...",
  "requires_approval": false,
  "mcp_servers": [],
  "external_apis": [],
  "risks": [],
  "error": null
}

Plan Execution

Execute Plan

Execute a compiled plan.

POST /api/autotask/execute

Request Body

Response

{
  "success": true,
  "task_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "running",
  "error": null
}

Simulate Plan

Simulate execution without making changes.

POST /api/autotask/simulate/:plan_id

Response

{
  "success": true,
  "confidence": 0.95,
  "risk_score": 0.1,
  "risk_level": "LOW",
  "step_outcomes": [
    {
      "step_id": "step-1",
      "step_name": "Create customers table",
      "would_succeed": true,
      "success_probability": 0.98,
      "failure_modes": []
    }
  ],
  "impact": {
    "risk_score": 0.1,
    "risk_level": "LOW",
    "data_impact": {
      "records_created": 0,
      "records_modified": 0,
      "records_deleted": 0,
      "tables_affected": ["customers"],
      "reversible": true
    },
    "cost_impact": {
      "api_costs": 0.01,
      "compute_costs": 0.005,
      "storage_costs": 0.001,
      "total_estimated_cost": 0.016
    },
    "time_impact": {
      "estimated_duration_seconds": 30,
      "blocking": false
    },
    "security_impact": {
      "risk_level": "LOW",
      "credentials_accessed": [],
      "external_systems": [],
      "concerns": []
    }
  },
  "side_effects": [],
  "recommendations": [],
  "error": null
}

Task Management

List Tasks

Get all tasks with optional filtering.

GET /api/autotask/list

Query Parameters

Response

{
  "tasks": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "Create CRM Application",
      "status": "running",
      "progress": 0.6,
      "current_step": 3,
      "total_steps": 5
    }
  ],
  "total": 1
}

Get Task Stats

Get summary statistics.

GET /api/autotask/stats

Response

{
  "total": 25,
  "running": 2,
  "pending": 5,
  "completed": 15,
  "failed": 3,
  "pending_approval": 1,
  "pending_decision": 0
}

Execute Task

Start execution of a specific task.

POST /api/autotask/:task_id/execute

Response

{
  "success": true,
  "task_id": "660e8400-e29b-41d4-a716-446655440001",
  "message": "Task execution started"
}

Pause Task

Pause a running task.

POST /api/autotask/:task_id/pause

Response

{
  "success": true,
  "message": "Task paused"
}

Resume Task

Resume a paused task.

POST /api/autotask/:task_id/resume

Response

{
  "success": true,
  "message": "Task resumed"
}

Cancel Task

Cancel a task.

POST /api/autotask/:task_id/cancel

Response

{
  "success": true,
  "message": "Task cancelled"
}

Simulate Task

Run simulation on an existing task.

POST /api/autotask/:task_id/simulate

Response

Same as Plan Simulation response.

Get Task Logs

Get execution logs for a task.

GET /api/autotask/:task_id/logs

Response

{
  "task_id": "660e8400-e29b-41d4-a716-446655440001",
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "level": "info",
      "message": "Task initialized"
    },
    {
      "timestamp": "2024-01-15T10:30:01Z",
      "level": "info",
      "message": "Step 1: Creating customers table"
    }
  ]
}

Decisions

Get Pending Decisions

Get decisions requiring user input.

GET /api/autotask/:task_id/decisions

Response

{
  "decisions": [
    {
      "id": "dec-001",
      "title": "Choose database type",
      "description": "Select the database type for the application",
      "options": [
        {"id": "opt-1", "label": "PostgreSQL", "description": "Recommended for production"},
        {"id": "opt-2", "label": "SQLite", "description": "Simple, file-based"}
      ],
      "default_option": "opt-1",
      "timeout_seconds": 3600
    }
  ]
}

Submit Decision

Submit a decision response.

POST /api/autotask/:task_id/decide

Request Body

Example Request

{
  "decision_id": "dec-001",
  "option_id": "opt-1"
}

Response

{
  "success": true,
  "message": "Decision submitted"
}

Approvals

Get Pending Approvals

Get actions requiring approval.

GET /api/autotask/:task_id/approvals

Response

{
  "approvals": [
    {
      "id": "apr-001",
      "title": "Bulk email send",
      "description": "This action will send 50 emails to customers",
      "risk_level": "MEDIUM",
      "impact_summary": "50 emails will be sent",
      "timeout_seconds": 3600
    }
  ]
}

Submit Approval

Approve or reject an action.

POST /api/autotask/:task_id/approve

Request Body

Example Request

{
  "approval_id": "apr-001",
  "action": "approve",
  "comment": "Verified recipient list"
}

Response

{
  "success": true,
  "message": "Action approved"
}

Recommendations

Apply Recommendation

Apply a recommendation from simulation results.

POST /api/autotask/recommendations/:rec_id/apply

Response

{
  "success": true,
  "recommendation_id": "rec-001",
  "message": "Recommendation applied successfully"
}

Error Responses

All endpoints return errors in this format:

{
  "success": false,
  "error": "Error description"
}

HTTP Status Codes

Next Steps

• Workflow Guide — Understanding task execution
• Examples — Real-world use cases
• Designer Guide — Modifying apps through conversation