openapi: 3.0.3
info:
  title: Onfleet Tasks API
  description: |
    The Onfleet Tasks API manages delivery and pickup tasks across the Onfleet
    last-mile delivery platform. Tasks are the atomic unit of work — each
    represents a single pickup or dropoff with a destination, recipient,
    completion window, and optional dependencies.
  version: '2.7'
  contact:
    name: Onfleet Support
    email: support@onfleet.com
    url: https://onfleet.com/support
  license:
    name: Onfleet Terms of Service
    url: https://onfleet.com/legal
servers:
  - url: https://onfleet.com/api/v2
    description: Production
security:
  - basicAuth: []
tags:
  - name: Tasks
paths:
  /tasks:
    post:
      tags: [Tasks]
      summary: Create Task
      description: Create a new pickup or dropoff task with a destination, recipient, and completion window.
      operationId: createTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreate'
      responses:
        '200':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/batch:
    post:
      tags: [Tasks]
      summary: Create Tasks In Batch
      description: Asynchronously create up to 100 tasks per request; results are returned via the taskBatchCreateJobCompleted webhook.
      operationId: createTaskBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tasks:
                  type: array
                  items:
                    $ref: '#/components/schemas/TaskCreate'
      responses:
        '200':
          description: Batch accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  jobId:
                    type: string
  /tasks/all:
    get:
      tags: [Tasks]
      summary: List Tasks
      description: Return a paginated collection of tasks; uses lastId-based pagination with up to 64 tasks per page.
      operationId: listTasks
      parameters:
        - name: from
          in: query
          required: true
          schema: {type: integer, format: int64}
          description: Start of the search range in Unix milliseconds.
        - name: to
          in: query
          schema: {type: integer, format: int64}
          description: End of the search range in Unix milliseconds.
        - name: lastId
          in: query
          schema: {type: string}
          description: Cursor returned from a previous call to walk pagination.
        - name: state
          in: query
          schema: {type: string}
          description: Comma-separated list of task state values (0=Unassigned, 1=Assigned, 2=Active, 3=Completed).
        - name: worker
          in: query
          schema: {type: string}
        - name: completeBeforeBefore
          in: query
          schema: {type: integer, format: int64}
        - name: completeAfterAfter
          in: query
          schema: {type: integer, format: int64}
        - name: dependencies
          in: query
          schema: {type: string}
        - name: containers
          in: query
          schema: {type: string}
      responses:
        '200':
          description: Paginated tasks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskList'
  /tasks/{taskId}:
    parameters:
      - name: taskId
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Tasks]
      summary: Get Single Task
      operationId: getTask
      responses:
        '200':
          description: Task
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Task'}
    put:
      tags: [Tasks]
      summary: Update Task
      operationId: updateTask
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/TaskUpdate'}
      responses:
        '200':
          description: Updated task
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Task'}
    delete:
      tags: [Tasks]
      summary: Delete Task
      operationId: deleteTask
      responses:
        '200':
          description: Task deleted
  /tasks/shortId/{shortId}:
    parameters:
      - name: shortId
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Tasks]
      summary: Get Task By Short ID
      operationId: getTaskByShortId
      responses:
        '200':
          description: Task
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Task'}
  /tasks/{taskId}/clone:
    post:
      tags: [Tasks]
      summary: Clone Task
      operationId: cloneTask
      parameters:
        - name: taskId
          in: path
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Cloned task
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Task'}
  /tasks/{taskId}/complete:
    post:
      tags: [Tasks]
      summary: Force-Complete Task
      operationId: forceCompleteTask
      parameters:
        - name: taskId
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                completionDetails:
                  type: object
                  properties:
                    success: {type: boolean}
                    notes: {type: string}
      responses:
        '200':
          description: Task completed
  /containers/workers/{workerId}:
    put:
      tags: [Tasks]
      summary: Assign Tasks To Worker
      description: Set the ordered list of task IDs assigned to a worker (replaces existing assignments unless type=APPEND).
      operationId: assignTasksToWorker
      parameters:
        - name: workerId
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tasks]
              properties:
                tasks:
                  type: array
                  items: {type: string}
                considerDependencies: {type: boolean}
      responses:
        '200':
          description: Worker container updated
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic auth using your Onfleet API key as the username with an empty password.
  schemas:
    Task:
      type: object
      properties:
        id: {type: string, description: 24-character resource identifier.}
        shortId: {type: string}
        organization: {type: string}
        timeCreated: {type: integer, format: int64}
        timeLastModified: {type: integer, format: int64}
        executor: {type: string}
        merchant: {type: string}
        creator: {type: string}
        worker: {type: string, nullable: true}
        destination: {$ref: '#/components/schemas/Destination'}
        recipients:
          type: array
          items: {$ref: '#/components/schemas/Recipient'}
        completeAfter: {type: integer, format: int64, nullable: true}
        completeBefore: {type: integer, format: int64, nullable: true}
        pickupTask: {type: boolean}
        dependencies:
          type: array
          items: {type: string}
        notes: {type: string}
        quantity: {type: integer}
        serviceTime: {type: integer}
        state: {type: integer, enum: [0, 1, 2, 3]}
        completionDetails: {$ref: '#/components/schemas/CompletionDetails'}
        feedback:
          type: array
          items: {$ref: '#/components/schemas/Feedback'}
        metadata:
          type: array
          items: {$ref: '#/components/schemas/Metadata'}
        trackingURL: {type: string, format: uri}
        trackingViewed: {type: boolean}
        eta: {type: integer, format: int64, nullable: true}
        delayTime: {type: integer, nullable: true}
        appearance:
          type: object
          properties:
            triangleColor: {type: string, nullable: true}
        container:
          type: object
          properties:
            type: {type: string, enum: [ORGANIZATION, TEAM, WORKER]}
            organization: {type: string}
    TaskCreate:
      type: object
      properties:
        merchant: {type: string}
        executor: {type: string}
        destination:
          oneOf:
            - {type: string}
            - {$ref: '#/components/schemas/Destination'}
        recipients:
          type: array
          items:
            oneOf:
              - {type: string}
              - {$ref: '#/components/schemas/Recipient'}
        completeAfter: {type: integer, format: int64}
        completeBefore: {type: integer, format: int64}
        pickupTask: {type: boolean}
        dependencies:
          type: array
          items: {type: string}
        notes: {type: string, maxLength: 10000}
        quantity: {type: integer}
        serviceTime: {type: integer}
        autoAssign: {$ref: '#/components/schemas/AutoAssign'}
        container: {type: object}
        metadata:
          type: array
          items: {$ref: '#/components/schemas/Metadata'}
        appearance:
          type: object
          properties:
            triangleColor: {type: string}
    TaskUpdate:
      type: object
      properties:
        notes: {type: string}
        completeAfter: {type: integer, format: int64}
        completeBefore: {type: integer, format: int64}
        pickupTask: {type: boolean}
        quantity: {type: integer}
        serviceTime: {type: integer}
        metadata:
          type: array
          items: {$ref: '#/components/schemas/Metadata'}
    TaskList:
      type: object
      properties:
        lastId: {type: string, nullable: true}
        tasks:
          type: array
          items: {$ref: '#/components/schemas/Task'}
    Destination:
      type: object
      properties:
        id: {type: string}
        address:
          type: object
          properties:
            unparsed: {type: string}
            number: {type: string}
            street: {type: string}
            city: {type: string}
            state: {type: string}
            postalCode: {type: string}
            country: {type: string}
            apartment: {type: string}
        location:
          type: array
          minItems: 2
          maxItems: 2
          items: {type: number}
          description: GeoJSON [longitude, latitude].
        notes: {type: string}
        warnings:
          type: array
          items: {type: string}
    Recipient:
      type: object
      properties:
        id: {type: string}
        name: {type: string}
        phone: {type: string, description: E.164 phone number.}
        notes: {type: string}
        skipSMSNotifications: {type: boolean}
        organization: {type: string}
    AutoAssign:
      type: object
      properties:
        mode: {type: string, enum: [distance, load]}
        team: {type: string}
        considerDependencies: {type: boolean}
        excludedWorkerIds:
          type: array
          items: {type: string}
        maxAssignedTaskCount: {type: integer}
    CompletionDetails:
      type: object
      properties:
        success: {type: boolean}
        time: {type: integer, format: int64, nullable: true}
        notes: {type: string}
        photoUploadIds:
          type: array
          items: {type: string}
        signatureUploadId: {type: string, nullable: true}
        events:
          type: array
          items:
            type: object
            properties:
              name: {type: string}
              time: {type: integer, format: int64}
    Feedback:
      type: object
      properties:
        time: {type: integer, format: int64}
        rating: {type: integer, minimum: 1, maximum: 5}
        comments: {type: string}
    Metadata:
      type: object
      required: [name, type, value]
      properties:
        name: {type: string}
        type: {type: string, enum: [boolean, number, string, object, array]}
        value: {}
        visibility:
          type: array
          items: {type: string, enum: [api, dashboard, worker]}