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

# Create a task

> Creates a task. When `aptletInstanceId` is set, the task is also mirrored as a
checklist entry on that card.

The task is attributed to an acting user who must belong to the company. With a
delegate token the user is taken from the token. With an API key (no associated
user), supply `userId` in the body — it must belong to the company or the
request is rejected.




## OpenAPI

````yaml /openapi.yaml post /api/tasks
openapi: 3.0.3
info:
  title: Aptly API
  version: '1.0'
  description: >
    The Aptly API lets you read and write cards on any Aptly board from external
    systems.


    All requests require an API key passed as the `x-token` header.

    API keys are scoped to your company and work across all boards.
servers:
  - url: https://core-api.getaptly.com
    description: Production
security:
  - ApiKeyHeader: []
paths:
  /api/tasks:
    post:
      tags:
        - Tasks
      summary: Create a task
      description: >
        Creates a task. When `aptletInstanceId` is set, the task is also
        mirrored as a

        checklist entry on that card.


        The task is attributed to an acting user who must belong to the company.
        With a

        delegate token the user is taken from the token. With an API key (no
        associated

        user), supply `userId` in the body — it must belong to the company or
        the

        request is rejected.
      operationId: createTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - assigneeId
                - dueAt
                - type
              properties:
                userId:
                  type: string
                  description: >
                    Acting user the task is attributed to (createdBy/updatedBy).

                    Required with API-key auth (must belong to the company);
                    ignored

                    with a delegate token, which supplies the user itself.
                title:
                  type: string
                assigneeId:
                  type: string
                  description: User id the task is assigned to.
                dueAt:
                  type: string
                  format: date-time
                type:
                  type: string
                  description: >-
                    Follow-up type — one of
                    email|comment|sms|voice|card|note|task|logActivity.
                note:
                  type: string
                  description: Task description.
                status:
                  type: string
                  description: One of backlog|notStarted|inProgress|onHold|completed.
                priority:
                  type: string
                  description: One of asap|high|medium|low.
                logType:
                  type: string
                  description: Required when type is "logActivity".
                aptletInstanceId:
                  type: string
                  description: >-
                    Card id — when set the task is mirrored onto the card
                    checklist.
                aptletUuid:
                  type: string
                channelId:
                  type: string
                streamId:
                  type: string
                fieldId:
                  type: string
                  description: Checklist array field on the card (defaults to "checklist").
                attachmentIds:
                  type: array
                  items:
                    type: string
                references:
                  type: array
                  items:
                    type: object
            example:
              title: Call the tenant
              assigneeId: usr_123
              dueAt: '2026-06-10T00:00:00.000Z'
              type: task
              priority: high
              status: notStarted
      responses:
        '200':
          description: Task created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskId:
                    type: string
        '400':
          description: Missing or invalid field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credential.
      security:
        - ApiKeyHeader: []
        - DelegateToken: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-token
    DelegateToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Delegate token issued by the platform. Format: `DelegateToken <token>`'

````