> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Task

> Update an existing scheduled task. Only the id field is required; any additional fields you include will be updated on the task. The response shape matches the GET endpoint (an array containing the updated task).



## OpenAPI

````yaml api-reference/openapi/releases.json PATCH /api/tasks
openapi: 3.1.0
info:
  title: Recoup API - Releases
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/tasks:
    patch:
      summary: Update scheduled task
      description: >-
        Update an existing scheduled task. Only the id field is required; any
        additional fields you include will be updated on the task. The response
        shape matches the GET endpoint (an array containing the updated task).
      requestBody:
        description: JSON object with `id` and optional fields to merge onto the task.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
            examples:
              updateTitleAndSchedule:
                summary: Change title and cron
                value:
                  id: aade2bce-55c7-468e-a606-c4e76fb2ea2a
                  title: Weekly Genre Pulse Check (rev)
                  schedule: 0 10 * * 4
              toggleEnabled:
                summary: Pause or resume a task
                value:
                  id: aade2bce-55c7-468e-a606-c4e76fb2ea2a
                  enabled: false
              changeModel:
                summary: Switch model only
                value:
                  id: aade2bce-55c7-468e-a606-c4e76fb2ea2a
                  model: claude-sonnet-4-20250514
      responses:
        '200':
          description: >-
            Task updated successfully. Body is a `TasksResponse` with the
            updated task in `tasks` (typically one task).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksResponse'
        '400':
          description: >-
            Bad request — missing `id`, empty strings where a field is provided,
            or other validation failure from the request body. The body reports
            the first Zod issue via `missing_fields` and `error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTaskValidationErrorResponse'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - account_id is outside caller authorization scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No task exists with the given `id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTaskFailureResponse'
              examples:
                notFound:
                  summary: Unknown task id
                  value:
                    status: error
                    error: Task not found
        '500':
          description: >-
            Internal server error while updating the task or syncing the
            Trigger.dev schedule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTaskFailureResponse'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    UpdateTaskRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: UUID of the task to update
          example: aade2bce-55c7-468e-a606-c4e76fb2ea2a
        title:
          type: string
          minLength: 1
          description: New descriptive title. If sent, must be a non-empty string.
          example: Weekly Genre Pulse Check (Updated)
        prompt:
          type: string
          minLength: 1
          description: >-
            New instruction/prompt executed by the task. If sent, must be a
            non-empty string.
          example: >-
            Execute this weekly genre analysis workflow and email a summary to
            the team.
        schedule:
          type: string
          minLength: 1
          description: >-
            New cron expression. If sent, must be non-empty and valid for your
            environment.
          example: 0 10 * * 4
        account_id:
          type: string
          format: uuid
          description: >-
            UUID of the account to update the task for. Only applicable when the
            authenticated account has access to multiple accounts via
            organization membership. If not provided, the task is updated for
            the API key's own account.
          example: 848cd58d-700f-4b38-ab4c-d9f52a1b2c3d
        artist_account_id:
          type: string
          format: uuid
          description: UUID of the artist account to associate with the task after update
          example: 1873859c-dd37-4e9a-9bac-80d35a1b2c3d
        enabled:
          type: boolean
          nullable: true
          description: >-
            Whether the task is enabled (`true` / `false`), or `null` to clear
            an explicit override depending on server rules.
          example: true
        model:
          type: string
          minLength: 1
          description: >-
            AI model identifier to use when the task runs. If sent, must be a
            non-empty string.
          example: claude-sonnet-4-20250514
    TasksResponse:
      type: object
      required:
        - status
        - tasks
      properties:
        status:
          type: string
          enum:
            - success
            - error
          description: Status of the request
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
          description: Array of task objects
        error:
          type: string
          description: Error message (only present if status is error)
    UpdateTaskValidationErrorResponse:
      type: object
      required:
        - status
        - missing_fields
        - error
      properties:
        status:
          type: string
          enum:
            - error
          description: Always `error` when validation fails
        missing_fields:
          type: array
          description: >-
            JSON path segments to the first field that failed validation (from
            Zod), e.g. `["id"]` or `["schedule"]`
          items:
            oneOf:
              - type: string
              - type: integer
        error:
          type: string
          description: Validation message for the first failing field
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    UpdateTaskFailureResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - error
          description: Always `error` for this response shape
        error:
          type: string
          description: Human-readable error message (for example `Task not found` on 404)
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the task
        title:
          type: string
          description: Descriptive title or name of the task
        prompt:
          type: string
          description: Detailed instruction or prompt for task execution
        schedule:
          type: string
          description: >-
            Cron expression defining when the task should execute (e.g., '0 10 *
            * *')
        account_id:
          type: string
          format: uuid
          description: Unique identifier for the associated account
        artist_account_id:
          type: string
          format: uuid
          description: Unique identifier for the associated artist account
        enabled:
          type: boolean
          nullable: true
          description: Whether the task is enabled. Defaults to true.
        trigger_schedule_id:
          type: string
          nullable: true
          description: Identifier for the trigger schedule associated with this task
        recent_runs:
          type: array
          items:
            $ref: '#/components/schemas/TaskRunResponse'
          description: Last 5 runs for this task, sourced from the Trigger.dev API.
        upcoming:
          type: array
          items:
            type: string
            format: date-time
          description: >-
            Next scheduled run times, sourced from the latest Trigger.dev run
            payload.
        owner_email:
          type: string
          nullable: true
          description: Primary email address for the task owner account when one exists.
        model:
          type: string
          nullable: true
          minLength: 1
          description: >-
            AI model identifier used when the task runs. When present as a
            string, must be non-empty; otherwise `null` if unset.
    TaskRunResponse:
      type: object
      description: >-
        Raw Trigger.dev SDK run object. The API passes through the SDK response
        without field mapping. See
        https://trigger.dev/docs/management/runs/retrieve for the full
        reference. When listing runs, `output`, `error`, `payload`, and
        `attempts` are not included.
      required:
        - id
        - status
        - taskIdentifier
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: The unique run identifier, prefixed with `run_`
        status:
          type: string
          enum:
            - PENDING_VERSION
            - DELAYED
            - QUEUED
            - EXECUTING
            - REATTEMPTING
            - FROZEN
            - COMPLETED
            - CANCELED
            - FAILED
            - CRASHED
            - INTERRUPTED
            - SYSTEM_FAILURE
          description: Current run status
        taskIdentifier:
          type: string
          description: >-
            The task type identifier (e.g. 'setup-sandbox',
            'run-sandbox-command')
        idempotencyKey:
          type: string
          nullable: true
          description: Idempotency key used to deduplicate trigger requests
        version:
          type: string
          description: The worker version that executed the run
        isTest:
          type: boolean
          description: Whether this is a test run
        createdAt:
          type: string
          format: date-time
          description: When the run was created (ISO 8601)
        updatedAt:
          type: string
          format: date-time
          description: When the run was last updated (ISO 8601)
        startedAt:
          type: string
          format: date-time
          nullable: true
          description: When execution started (null if not yet started)
        finishedAt:
          type: string
          format: date-time
          nullable: true
          description: When the run finished (null if still running)
        delayedUntil:
          type: string
          format: date-time
          nullable: true
          description: If delayed, when the run becomes eligible to execute
        ttl:
          description: >-
            Time-to-live. If the run is not started within this duration, it
            expires.
          nullable: true
        expiredAt:
          type: string
          format: date-time
          nullable: true
          description: When the run expired (null if not expired)
        tags:
          type: array
          items:
            type: string
          description: Tags associated with this run (max 10)
        metadata:
          type: object
          nullable: true
          description: JSON metadata attached to the run
        costInCents:
          type: number
          description: Compute cost of the run in cents
        baseCostInCents:
          type: number
          description: Base invocation cost in cents
        durationMs:
          type: number
          description: Compute duration in milliseconds
        env:
          type: object
          description: Environment the run executed in
          properties:
            id:
              type: string
            name:
              type: string
            user:
              type: string
              nullable: true
        depth:
          type: integer
          description: Nesting depth for child runs
        batchId:
          type: string
          nullable: true
          description: Batch ID if triggered as part of a batch
        triggerFunction:
          type: string
          enum:
            - trigger
            - triggerAndWait
            - batchTrigger
            - batchTriggerAndWait
          description: The function used to trigger this run
        payload:
          description: Input payload for the task. Only present when retrieving by runId.
          nullable: true
        output:
          description: >-
            Task output data. Only present when retrieving by runId, and only
            populated when `status` is `COMPLETED`. Shape varies by
            `taskIdentifier`. The `create-content` task returns the schema
            below; other tasks return their own.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/CreateContentRunOutput'
            - type: object
              description: Generic task output (for tasks not yet schema'd)
        error:
          type: object
          nullable: true
          description: >-
            Error details if the run failed. Only present when retrieving by
            runId.
          properties:
            message:
              type: string
              description: Human-readable error message
            name:
              type: string
              description: Error name or type
            stackTrace:
              type: string
              description: Stack trace
        attempts:
          type: array
          description: Attempt history. Only present when retrieving by runId.
          items:
            type: object
            properties:
              id:
                type: string
                description: Attempt ID, prefixed with `attempt_`
              status:
                type: string
                enum:
                  - PENDING
                  - EXECUTING
                  - PAUSED
                  - COMPLETED
                  - FAILED
                  - CANCELED
              createdAt:
                type: string
                format: date-time
              updatedAt:
                type: string
                format: date-time
              startedAt:
                type: string
                format: date-time
                nullable: true
              completedAt:
                type: string
                format: date-time
                nullable: true
              error:
                type: object
                nullable: true
                properties:
                  message:
                    type: string
                  name:
                    type: string
                  stackTrace:
                    type: string
        schedule:
          type: object
          nullable: true
          description: >-
            Schedule information if triggered by a schedule. Only present when
            retrieving by runId.
        relatedRuns:
          type: object
          nullable: true
          description: >-
            Related run references (root, parent, children). Only present when
            retrieving by runId.
    CreateContentRunOutput:
      type: object
      description: >-
        Output payload for a `create-content` task run. Returned in `output`
        when `status` is `COMPLETED`. Agents should poll
        `/api/tasks/runs?runId=…` and read these fields once the run is done.
      required:
        - videoSourceUrl
        - imageUrl
        - captionText
        - template
      properties:
        videoSourceUrl:
          type: string
          format: uri
          description: >-
            URL to the rendered final 9:16 video (image + motion + audio +
            caption already composed).
        imageUrl:
          type: string
          format: uri
          description: URL to the base image used for video generation.
        captionText:
          type: string
          description: The caption text burned into the video.
        template:
          type: string
          description: >-
            Template id used for this run (e.g. `album-record-store`,
            `artist-caption-bedroom`).
          example: artist-caption-bedroom
        lipsync:
          type: boolean
          description: Whether lipsync was applied (audio-driven mouth animation).
        audio:
          type: object
          description: Metadata about the song clip used in the final composition.
          properties:
            songTitle:
              type: string
            songFilename:
              type: string
            startSeconds:
              type: number
              description: Offset into the source song where the clip starts.
            durationSeconds:
              type: number
              description: Length of the audio clip in seconds.
            clipLyrics:
              type: string
              nullable: true
              description: Lyrics for the chosen clip, when available.
            clipMood:
              type: string
              nullable: true
              description: Inferred mood for the chosen clip, when available.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Recoup API key. [Learn more](/quickstart#api-keys).
    bearerAuth:
      type: http
      scheme: bearer

````