---
title: "Create an externally controlled task"
method: POST
path: "/v1/tasks/external"
tags: ["Adam API"]
---

# Create an externally controlled task

`POST /v1/tasks/external`

## Request

- Base URL: `https://api.adam.new`
- URL: `https://api.adam.new/v1/tasks/external`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.adam.new/auth/oauth2/authorize`
    - Token URL: `https://api.adam.new/auth/oauth2/token` scopes: `tasks:write`
- TypeScript: <https://skmtc.dev/adam/apis/adam-api/docs/v1/tasks/external/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates an idle task for an external client. No Adam model is selected, no inference or agent run starts, and no compute is provisioned. Attachments are immutable task inputs from POST /v1/uploads and additionally require files:read and files:write.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreatePublicApiExternalTaskRequestDto
  - `attachments` object[]
    - `uploadId` string, required
  - `prompt` string: The user's request to save in task history. This does not start an Adam agent.
  - `title` string
  - `projectId` string, uuid

## Response `201`

- GetPublicApiTaskResponseDto
  - `task` object, required
    - `id` string, required
    - `title` string, required
    - `status` 'idle' | 'queued' | 'running' | 'awaiting_input' | 'completed' | 'cancelled' | 'failed', required
    - `executionMode` 'adam' | 'external'
    - `projectId` string, nullable, required
    - `model` object, nullable, required
      - `slug` string, nullable, required
      - `fast` boolean, required
      - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable, required
    - `pendingInteraction` object, nullable, required
      - `id` string, required
      - `type` 'question' | 'approval', required
      - `prompt` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
  - `messages` object[], required
    - `id` string, required
    - `role` 'user' | 'assistant', required
    - `parts` union[], required
      - union
        - object
          - `type` 'reasoning', required
          - `text` string, required
        - object
          - `type` 'text', required
          - `text` string, required
        - object
          - `type` 'file', required
          - `id` string, nullable, required
          - `versionId` string, uuid
          - `name` string, nullable, required
          - `mediaType` string, required
          - `downloadUrl` string, uri, required
        - object
          - `type` 'source_url', required
          - `sourceId` string, required
          - `url` string, uri, required
          - `title` string, nullable, required
        - object
          - `type` 'source_document', required
          - `sourceId` string, required
          - `mediaType` string, required
          - `title` string, required
          - `filename` string, nullable, required
        - object
          - `type` 'reasoning_file', required
          - `mediaType` string, required
          - `url` string, uri, required
        - object
          - `type` 'data', required
          - `name` string, required
          - `id` string, nullable, required
          - `data` union, required
            - string
            - number
            - boolean
            - GetPublicApiTaskResponseDtoSchema0[]
            - object
        - object
          - `type` 'custom', required
          - `kind` string, required
          - `providerMetadata` union
            - string
            - number
            - boolean
            - GetPublicApiTaskResponseDtoSchema0[]
            - object
        - object
          - `type` 'step_start', required
        - object
          - `type` 'tool_call', required
          - `toolCallId` string, required
          - `name` string, required
          - `input` union
            - string
            - number
            - boolean
            - GetPublicApiTaskResponseDtoSchema0[]
            - object
        - object
          - `type` 'tool_result', required
          - `toolCallId` string, required
          - `name` string, required
          - `status` 'success', required
          - `output` union
            - string
            - number
            - boolean
            - GetPublicApiTaskResponseDtoSchema0[]
            - object
        - object
          - `type` 'tool_result', required
          - `toolCallId` string, required
          - `name` string, required
          - `status` 'error', required
          - `error` string
        - object
          - `type` 'tool_result', required
          - `toolCallId` string, required
          - `name` string, required
          - `status` 'denied', required
    - `createdAt` string, date-time, required

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid Bearer credential
- `402`: Payment or subscription required
- `403`: Credential is missing a required scope
- `404`: Resource not found
- `409`: Request conflict
- `429`: Rate limit exceeded
- `500`: Internal API error

## Changes

- **2026-10-30** `11052d3a9e59`: 2 info
  - added the new optional request property `attachments`
  - added the optional property `messages/items/parts/items/anyOf[subschema #3]/versionId` to the response with the `201` status
- **2026-10-29** `4baea94e5dbc`: 2 breaking, 5 info
  - the response property `task/pendingInteraction/anyOf[subschema #1]/prompt` became nullable for the status `201`
  - the response property `task/projectId` became nullable for the status `201`
  - added `subschema #3, subschema #4, subschema #5, subschema #7` to the `messages/items/parts/items/` response property `anyOf` list for the response status `201`
  - removed `subschema #3, subschema #4, subschema #5, subschema #7` from the `messages/items/parts/items/` response property `anyOf` list for the response status `201`
  - …3 more
- **2026-10-13** `9d7a35f993ac`: 1 info
  - added the new optional request property `prompt`
- **2026-10-09** `135cef4f7586`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adam/apis/adam-api/changes/v1/tasks/external/post.md)

---

[API](https://skmtc.dev/adam/apis/adam-api.md) - [All operations](https://skmtc.dev/adam/apis/adam-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adam/apis/adam-api/revisions/38d4c566646c?raw)