> ## 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.

# Create Task

> 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).



## OpenAPI

````yaml api-reference/openapi/releases.json POST /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:
    post:
      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'
        '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'
components:
  schemas:
    CreateTaskRequest:
      type: object
      required:
        - title
        - prompt
        - schedule
        - artist_account_id
      properties:
        title:
          type: string
          description: Descriptive title of the task
          example: Weekly Genre Pulse Check
        prompt:
          type: string
          description: Instruction/prompt executed by the task
          example: >-
            Execute this weekly genre analysis workflow and email a summary to
            the team.
        schedule:
          type: string
          description: >-
            Cron expression defining when the task runs (e.g., '0 9 * * 4' for
            Thursdays at 9 AM)
          example: 0 9 * * 4
        account_id:
          type: string
          format: uuid
          description: >-
            UUID of the account to create the task for. Only applicable when the
            authenticated account has access to multiple accounts via
            organization membership. If not provided, the task is created for
            the API key's own account.
          example: 848cd58d-700f-4b38-ab4c-d9f52a1b2c3d
        artist_account_id:
          type: string
          format: uuid
          description: UUID of the associated artist account
          example: 1873859c-dd37-4e9a-9bac-80d35a1b2c3d
    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)
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    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.

````