Files
task_pilot/contracts/openapi.json
T

1324 lines
31 KiB
JSON

{
"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"
]
},
"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
}
}
}
}