docs(autotask): Add API reference documentation for AutoTask endpoints
- Document all 17 API endpoints with request/response examples - Add intent types reference table - Add error response format documentation - Add HTTP status codes reference
This commit is contained in:
parent
baf4aa6125
commit
3f96aa6e1c
1 changed files with 563 additions and 0 deletions
563
src/17-autonomous-tasks/api-reference.md
Normal file
563
src/17-autonomous-tasks/api-reference.md
Normal file
|
|
@ -0,0 +1,563 @@
|
|||
# API Reference
|
||||
|
||||
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
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `intent` | string | Yes | Natural language description |
|
||||
| `auto_process` | boolean | No | If true, process immediately (default: true) |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"intent": "Create an app for my clinic with patients and appointments",
|
||||
"auto_process": true
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `APP_CREATE` | Create full HTMX application |
|
||||
| `TODO` | Save task to tasks table |
|
||||
| `MONITOR` | Create ON CHANGE event handler |
|
||||
| `ACTION` | Execute immediately |
|
||||
| `SCHEDULE` | Create SET SCHEDULE automation |
|
||||
| `GOAL` | Autonomous LLM loop with metrics |
|
||||
| `TOOL` | Create voice/chat command |
|
||||
|
||||
---
|
||||
|
||||
## Intent Compilation
|
||||
|
||||
### Compile Intent
|
||||
|
||||
Compile an intent into an execution plan without executing.
|
||||
|
||||
**POST** `/api/autotask/compile`
|
||||
|
||||
#### Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `intent` | string | Yes | Natural language description |
|
||||
| `execution_mode` | string | No | `semi-automatic`, `supervised`, `fully-automatic`, `dry-run` |
|
||||
| `priority` | string | No | `critical`, `high`, `medium`, `low`, `background` |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"intent": "Create a CRM for tracking customers and orders",
|
||||
"execution_mode": "semi-automatic",
|
||||
"priority": "medium"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `plan_id` | string | Yes | ID from compile response |
|
||||
| `execution_mode` | string | No | Override execution mode |
|
||||
| `priority` | string | No | Override priority |
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `filter` | string | `all`, `running`, `pending`, `completed`, `failed` |
|
||||
| `status` | string | Specific status filter |
|
||||
| `priority` | string | Priority filter |
|
||||
| `limit` | integer | Max results (default: 50) |
|
||||
| `offset` | integer | Pagination offset |
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Task paused"
|
||||
}
|
||||
```
|
||||
|
||||
### Resume Task
|
||||
|
||||
Resume a paused task.
|
||||
|
||||
**POST** `/api/autotask/:task_id/resume`
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Task resumed"
|
||||
}
|
||||
```
|
||||
|
||||
### Cancel Task
|
||||
|
||||
Cancel a task.
|
||||
|
||||
**POST** `/api/autotask/:task_id/cancel`
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `decision_id` | string | Yes | Decision ID |
|
||||
| `option_id` | string | No | Selected option ID |
|
||||
| `skip` | boolean | No | Skip and use default |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"decision_id": "dec-001",
|
||||
"option_id": "opt-1"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Decision submitted"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Approvals
|
||||
|
||||
### Get Pending Approvals
|
||||
|
||||
Get actions requiring approval.
|
||||
|
||||
**GET** `/api/autotask/:task_id/approvals`
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `approval_id` | string | Yes | Approval ID |
|
||||
| `action` | string | Yes | `approve`, `reject`, `skip` |
|
||||
| `comment` | string | No | Optional comment |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"approval_id": "apr-001",
|
||||
"action": "approve",
|
||||
"comment": "Verified recipient list"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Action approved"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Apply Recommendation
|
||||
|
||||
Apply a recommendation from simulation results.
|
||||
|
||||
**POST** `/api/autotask/recommendations/:rec_id/apply`
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"recommendation_id": "rec-001",
|
||||
"message": "Recommendation applied successfully"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return errors in this format:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Error description"
|
||||
}
|
||||
```
|
||||
|
||||
### HTTP Status Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 200 | Success |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not found |
|
||||
| 500 | Internal server error |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Workflow Guide](./workflow.md) — Understanding task execution
|
||||
- [Examples](./examples.md) — Real-world use cases
|
||||
- [Designer Guide](./designer.md) — Modifying apps through conversation
|
||||
Loading…
Add table
Reference in a new issue