Create Task

{
  "description": "Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array).",
  "requestBody": {
    "description": "Task to create",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateTaskRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Task created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TasksResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing required fields or invalid body",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "402": {
      "description": "Payment required - the account's plan does not allow this task. `limit` is `task_count` when the account already has `task_limit` enabled tasks, or `min_cadence` when the cron schedule fires more often than `min_cadence_minutes` allows. Nothing is written; upgrade at `billingUrl`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlanLimitError"
          },
          "examples": {
            "taskCount": {
              "summary": "Free account creating a second task",
              "value": {
                "status": "error",
                "error": "plan_limit",
                "limit": "task_count",
                "message": "Free includes 1 task. Starter includes 3, Pro is unlimited.",
                "plan": "free",
                "task_limit": 1,
                "min_cadence_minutes": 10080,
                "current_task_count": 1,
                "billingUrl": "https://app.recoupable.dev/plan"
              }
            },
            "minCadence": {
              "summary": "Free account scheduling a daily task",
              "value": {
                "status": "error",
                "error": "plan_limit",
                "limit": "min_cadence",
                "message": "Free runs tasks weekly at most. Starter runs daily, Pro runs hourly.",
                "plan": "free",
                "task_limit": 1,
                "min_cadence_minutes": 10080,
                "current_task_count": 0,
                "billingUrl": "https://app.recoupable.dev/plan"
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - account_id is outside caller authorization scope",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}