{
  "openapi": "3.1.0",
  "info": {
    "title": "TaskPilot API",
    "description": "Local task scheduling and process management API.",
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "paths": {
    "/api/v1/cron/preview": {
      "post": {
        "tags": [
          "system"
        ],
        "operationId": "preview_cron",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CronPreviewRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Upcoming cron occurrences",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CronPreviewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid cron preview request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/events": {
      "get": {
        "tags": [
          "runs"
        ],
        "operationId": "execution_events",
        "responses": {
          "200": {
            "description": "Run status and log events",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "tags": [
          "system"
        ],
        "operationId": "health",
        "responses": {
          "200": {
            "description": "TaskPilot API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/runs/{run_id}": {
      "get": {
        "tags": [
          "runs"
        ],
        "operationId": "get_run",
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "description": "Run identifier",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task run detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskRunResponse"
                }
              }
            }
          },
          "404": {
            "description": "Run not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/runs/{run_id}/cancel": {
      "post": {
        "tags": [
          "runs"
        ],
        "operationId": "cancel_run",
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "description": "Run identifier",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Cancellation requested",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskRunResponse"
                }
              }
            }
          },
          "404": {
            "description": "Run not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Run is not cancellable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/runs/{run_id}/logs": {
      "get": {
        "tags": [
          "runs"
        ],
        "operationId": "get_run_logs",
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "description": "Run identifier",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incremental task run log",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogChunkResponse"
                }
              }
            }
          },
          "404": {
            "description": "Run not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/runs/{run_id}/logs/download": {
      "get": {
        "tags": [
          "runs"
        ],
        "operationId": "download_run_logs",
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "description": "Run identifier",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plain text task log",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Run or log not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/session": {
      "get": {
        "tags": [
          "system"
        ],
        "operationId": "session",
        "responses": {
          "200": {
            "description": "Local API session token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks": {
      "get": {
        "tags": [
          "tasks"
        ],
        "operationId": "list_tasks",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "enabled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "action_type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/TaskActionType"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated task list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "tasks"
        ],
        "operationId": "create_task",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTaskRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Task created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Task ID already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks/{id}": {
      "get": {
        "tags": [
          "tasks"
        ],
        "operationId": "get_task",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Stable task identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "tasks"
        ],
        "operationId": "update_task",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Stable task identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTaskRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Task updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "tasks"
        ],
        "operationId": "delete_task",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Stable task identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Task deleted"
          },
          "404": {
            "description": "Task not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks/{id}/disable": {
      "post": {
        "tags": [
          "tasks"
        ],
        "operationId": "disable_task",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Stable task identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks/{id}/enable": {
      "post": {
        "tags": [
          "tasks"
        ],
        "operationId": "enable_task",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Stable task identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task enabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks/{id}/run": {
      "post": {
        "tags": [
          "runs"
        ],
        "operationId": "run_task",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Stable task identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Manual run accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskRunResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Action executor not implemented",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks/{id}/runs": {
      "get": {
        "tags": [
          "runs"
        ],
        "operationId": "list_task_runs",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Stable task identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/RunStatus"
            }
          },
          {
            "name": "trigger",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/RunTrigger"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task run history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskRunListResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ConcurrencyPolicy": {
        "type": "string",
        "enum": [
          "skip"
        ]
      },
      "CreateTaskRequest": {
        "type": "object",
        "required": [
          "id",
          "name",
          "cron",
          "action"
        ],
        "properties": {
          "action": {
            "$ref": "#/components/schemas/TaskAction"
          },
          "concurrency_policy": {
            "$ref": "#/components/schemas/ConcurrencyPolicy"
          },
          "cron": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "retry_policy": {
            "$ref": "#/components/schemas/RetryPolicy"
          },
          "timeout_secs": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "timezone": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CronPreviewRequest": {
        "type": "object",
        "required": [
          "expression",
          "timezone",
          "count"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "expression": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CronPreviewResponse": {
        "type": "object",
        "required": [
          "timezone",
          "runs"
        ],
        "properties": {
          "runs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "timezone": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "code",
          "message",
          "details"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "field": {
            "type": [
              "string",
              "null"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": [
          "status",
          "service",
          "version"
        ],
        "properties": {
          "service": {
            "type": "string",
            "description": "Stable service identifier."
          },
          "status": {
            "type": "string",
            "description": "Current service status."
          },
          "version": {
            "type": "string",
            "description": "Backend package version."
          }
        }
      },
      "HttpMethod": {
        "type": "string",
        "enum": [
          "GET",
          "POST"
        ]
      },
      "LogChunkResponse": {
        "type": "object",
        "required": [
          "content",
          "next_offset",
          "complete"
        ],
        "properties": {
          "complete": {
            "type": "boolean"
          },
          "content": {
            "type": "string"
          },
          "next_offset": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "RetryPolicy": {
        "type": "object",
        "properties": {
          "delay_secs": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "max_attempts": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "RunStatus": {
        "type": "string",
        "enum": [
          "queued",
          "running",
          "succeeded",
          "failed",
          "timed_out",
          "cancelled",
          "skipped"
        ]
      },
      "RunTrigger": {
        "type": "string",
        "enum": [
          "schedule",
          "manual",
          "retry"
        ]
      },
      "SessionResponse": {
        "type": "object",
        "required": [
          "token"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "Random per-process token required for mutating browser requests."
          }
        }
      },
      "TaskAction": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "working_dir",
              "interpreter",
              "script",
              "type"
            ],
            "properties": {
              "args": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "env": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "propertyNames": {
                  "type": "string"
                }
              },
              "interpreter": {
                "type": "string"
              },
              "script": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "script"
                ]
              },
              "venv": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "working_dir": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "url",
              "method",
              "type"
            ],
            "properties": {
              "body": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "expected_status": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 0
                }
              },
              "headers": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "propertyNames": {
                  "type": "string"
                }
              },
              "method": {
                "$ref": "#/components/schemas/HttpMethod"
              },
              "type": {
                "type": "string",
                "enum": [
                  "http"
                ]
              },
              "url": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "executable",
              "type"
            ],
            "properties": {
              "args": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "env": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "propertyNames": {
                  "type": "string"
                }
              },
              "executable": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "process"
                ]
              },
              "working_dir": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        ]
      },
      "TaskActionType": {
        "type": "string",
        "enum": [
          "script",
          "http",
          "process"
        ]
      },
      "TaskListResponse": {
        "type": "object",
        "required": [
          "items",
          "page",
          "page_size",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskResponse"
            }
          },
          "page": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "page_size": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "TaskResponse": {
        "type": "object",
        "required": [
          "id",
          "name",
          "cron",
          "timezone",
          "enabled",
          "timeout_secs",
          "concurrency_policy",
          "retry_policy",
          "action",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "action": {
            "$ref": "#/components/schemas/TaskAction"
          },
          "concurrency_policy": {
            "$ref": "#/components/schemas/ConcurrencyPolicy"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "cron": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "retry_policy": {
            "$ref": "#/components/schemas/RetryPolicy"
          },
          "timeout_secs": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "timezone": {
            "type": "string"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TaskRunListResponse": {
        "type": "object",
        "required": [
          "items",
          "page",
          "page_size",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskRunResponse"
            }
          },
          "page": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "page_size": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "TaskRunResponse": {
        "type": "object",
        "required": [
          "id",
          "task_id",
          "trigger",
          "status",
          "created_at"
        ],
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_ms": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "minimum": 0
          },
          "error_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "exit_code": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "status": {
            "$ref": "#/components/schemas/RunStatus"
          },
          "task_id": {
            "type": "string"
          },
          "trigger": {
            "$ref": "#/components/schemas/RunTrigger"
          }
        }
      },
      "UpdateTaskRequest": {
        "type": "object",
        "required": [
          "name",
          "cron",
          "action"
        ],
        "properties": {
          "action": {
            "$ref": "#/components/schemas/TaskAction"
          },
          "concurrency_policy": {
            "$ref": "#/components/schemas/ConcurrencyPolicy"
          },
          "cron": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "retry_policy": {
            "$ref": "#/components/schemas/RetryPolicy"
          },
          "timeout_secs": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "timezone": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  }
}