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

# Create task

> Start an agent run in a cloud workspace.

Send a `command` describing the work. The response includes the new `task` and its first `job`.

## Cloud tasks

The agent selects repositories from the workspace's connected repos. Set `agent` to a complete `provider/model` ID or use the workspace's [routing defaults](/agent-config/routing). `reasoningEffort` selects a supported effort level.

Normal tasks use `"SWE"` and run in their own fork of the workspace environment. Use `userIntent: "DEV_ENVIRONMENT"` to run in the main environment instead (Fork off in the app), for example to set it up or fix it. For planning, start `command` with `/plan`; approve the plan in the task chat, or send a follow-up starting with `/agent` to implement it.

## Attachments and compatibility

Pass attachment content as `data:` URLs in `files`. Remote HTTP URLs are not fetched. Legacy `userIntent` values `PLAN`, `ASK`, and `GOAL` are accepted as `SWE`; use native commands in `command` for planning or supported goal tracking.


## OpenAPI

````yaml openapi.json POST /tasks
openapi: 3.0.3
info:
  title: Twill API
  version: 1.0.0
  description: Programmatically create and manage Twill tasks via REST API.
servers:
  - url: https://twill.ai/api/v1
security:
  - bearerAuth: []
tags:
  - name: Tasks
    description: Create and manage tasks.
paths:
  /tasks:
    post:
      tags:
        - Tasks
      summary: Create task
      description: Create a new task and start an agent run.
      operationId: createTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            example:
              command: Add a dark mode toggle to the settings page
              userIntent: SWE
              agent: claude-code/sonnet
              files:
                - filename: design-spec.md
                  mediaType: text/markdown
                  url: data:text/markdown;base64,IyBEZXNpZ24gc3BlYw==
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTaskResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Workspace credit limit reached.
        '409':
          description: Execution location changed or the computer is unavailable
        '429':
          $ref: '#/components/responses/RateLimitedError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateTaskRequest:
      type: object
      required:
        - command
      properties:
        command:
          type: string
          description: >-
            Task description or instructions for the agent. Include a routing
            /trigger to select a harness, model, and effort config. Start with
            /plan to have the harness plan first, or /goal (Claude Code and
            Codex) to track a goal.
          minLength: 1
        agent:
          type: string
          description: >-
            Optional explicit harness. Must be a complete provider/model id
            (e.g. claude-code/opus, codex/gpt-6.1-sol,
            open-code/openai/gpt-6-sol); a provider-only value is rejected.
            Overrides routing for the task.
        userIntent:
          type: string
          enum:
            - SWE
            - SCHEDULE
            - DEV_ENVIRONMENT
          default: SWE
          description: >-
            Where the task runs: SWE (default) runs it in its own fork of the
            workspace environment; DEV_ENVIRONMENT runs it in the main
            environment (Fork off in the app), so what it installs or configures
            stays for future tasks. SCHEDULE is used by automations and runs
            like SWE. The legacy values PLAN, ASK, and GOAL are still accepted
            for backward compatibility and treated as SWE; start the command
            with /plan to plan first.
        title:
          type: string
          description: Optional task title (auto-generated if not provided).
        files:
          type: array
          description: Optional file attachments provided as UI message file parts.
          items:
            $ref: '#/components/schemas/FilePart'
        executionTarget:
          $ref: '#/components/schemas/ExecutionTarget'
        reasoningEffort:
          type: string
          enum:
            - low
            - medium
            - high
            - xhigh
            - max
            - ultra
          description: Reasoning effort supported by the selected model.
        parentId:
          type: string
          description: Optional parent task ID.
    CreateTaskResponse:
      type: object
      required:
        - task
        - job
      properties:
        task:
          $ref: '#/components/schemas/TaskSummary'
        job:
          $ref: '#/components/schemas/JobSummary'
    FilePart:
      type: object
      required:
        - filename
        - mediaType
        - url
      properties:
        filename:
          type: string
          description: Original file name shown to the agent.
        mediaType:
          type: string
          description: MIME type (for example text/plain, image/png).
        url:
          type: string
          description: >-
            File content inlined as a data: URL (for example
            data:text/markdown;base64,...). Remote http(s): URLs are not
            fetched.
    ExecutionTarget:
      type: object
      required:
        - kind
      additionalProperties: false
      description: >-
        API keys are cloud-only. Local project chats are started in Twill
        Desktop.
      properties:
        kind:
          type: string
          enum:
            - cloud
    TaskSummary:
      type: object
      required:
        - id
        - slug
        - title
        - url
      properties:
        id:
          type: string
        slug:
          type: string
        title:
          type: string
        url:
          type: string
    JobSummary:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/JobStatus'
    ApiErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
    JobStatus:
      type: string
      enum:
        - PENDING
        - IN_PROGRESS
        - COMPLETED
        - FAILED
        - CANCELLED
  responses:
    ValidationError:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          examples:
            invalidBody:
              value:
                error:
                  code: validation_error
                  message: Invalid request body
                  details:
                    issues:
                      - field: command
                        message: command is required
    UnauthorizedError:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error:
              code: unauthorized
              message: Invalid or missing API key
    RateLimitedError:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded. Max 100 requests per minute.
    InternalError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error:
              code: internal_error
              message: Server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.