{
  "openapi": "3.1.0",
  "info": {
    "title": "TaskBullet Agent API",
    "description": "Delegate tasks from AI agents and LLMs to real human virtual assistants (Human-in-the-loop).",
    "version": "1.0.0",
    "contact": {
      "name": "TaskBullet Support",
      "url": "https://taskbullet.com"
    }
  },
  "servers": [
    {
      "url": "https://taskbullet.com/api/v1",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your TaskBullet Agent API Key (begins with tb_live_)"
      }
    },
    "schemas": {
      "TaskStatus": {
        "type": "string",
        "enum": ["pending", "in_progress", "completed", "failed"],
        "description": "The current status of the task."
      },
      "TaskPriority": {
        "type": "string",
        "enum": ["low", "normal", "high"],
        "default": "normal",
        "description": "The priority level of the task."
      }
    }
  },
  "paths": {
    "/delegate": {
      "post": {
        "summary": "Delegate a Task",
        "description": "Dispatches a new task to a human virtual assistant.",
        "operationId": "delegateTask",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title"],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "A clear, concise title or directive for the task."
                  },
                  "description": {
                    "type": "string",
                    "description": "Detailed instructions, context, or constraints for the virtual assistant."
                  },
                  "priority": {
                    "$ref": "#/components/schemas/TaskPriority"
                  },
                  "webhookUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "An optional URL. TaskBullet will POST a signed webook here when the task completes."
                  },
                  "sourceAgent": {
                    "type": "string",
                    "description": "Optional identifier for the calling agent (e.g. 'claude-3-opus', 'my-custom-gpt'). Used for audit trails and routing context."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task successfully received and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "taskId": { "type": "string", "description": "Stable external ID used to track the task." },
                    "status": { "type": "string", "enum": ["received"] },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad Request (e.g. missing title)" },
          "401": { "description": "Unauthorized (Invalid or missing API key)" },
          "402": { "description": "Payment Required (No hour balance available)" },
          "409": { "description": "Conflict (Account not fully provisioned)" },
          "429": { "description": "Too Many Requests (Rate limit exceeded)" }
        }
      }
    },
    "/tasks": {
      "get": {
        "summary": "List Delegated Tasks",
        "description": "Fetch a list of recent tasks delegated via the Agent API.",
        "operationId": "listTasks",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter tasks by status.",
            "schema": {
              "type": "string",
              "enum": ["pending", "in_progress", "completed", "failed", "all"],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of tasks.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tasks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "taskId": { "type": "string" },
                          "status": { "$ref": "#/components/schemas/TaskStatus" },
                          "priority": { "$ref": "#/components/schemas/TaskPriority" },
                          "createdAt": { "type": "string", "format": "date-time" },
                          "completedAt": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/tasks/{taskId}": {
      "get": {
        "summary": "Get Task Status",
        "description": "Poll the current status and result of a specific task.",
        "operationId": "getTask",
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "description": "The stable ID returned when the task was delegated.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Task status and result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "taskId": { "type": "string" },
                    "status": { "$ref": "#/components/schemas/TaskStatus" },
                    "priority": { "$ref": "#/components/schemas/TaskPriority" },
                    "createdAt": { "type": "string", "format": "date-time" },
                    "result": { "type": "string", "description": "Notes or deliverables from the human VA (only present if completed)." },
                    "completedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "404": { "description": "Task not found" }
        }
      }
    }
  }
}