Clockify Task API

openapi: 3.2.0
info:
  description: '## Introduction

    By using this REST API, you can easily integrate Clockify with your own add-ons, push and pull data

    between Clockify and other tools, and create custom add-ons on CAKE.com Marketplace.'
  title: Clockify Task API
  version: v1
  x-logo:
    altText: Clockify logo
    url: https://clockify.me/downloads/clockify_logo_primary_black_margin.png
tags:
- name: Task
  x-displayName: Task
paths:
  /v1/workspaces/{workspaceId}/projects/{projectId}/tasks:
    servers:
    - url: https://api.clockify.me/api
    get:
      operationId: getTasks
      parameters:
      - description: Represents a project identifier across the system.
        example: 25b687e29ae1f428e7ebe123
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: If provided, you'll get a filtered list of tasks that matches the provided string in their name.
        example: Bugfixing
        in: query
        name: name
        required: false
        schema:
          type: string
          description: If provided, you'll get a filtered list of tasks that matches the provided string in their name.
          example: Bugfixing
      - description: Flag to toggle on/off strict search mode. When set to true, search by name only will return tasks whose name exactly matches the string value given for the 'name' parameter. When set to false, results will also include tasks whose name contain the string value, but could be longer than the string value itself. For example, if there is a task with the name 'applications', and the search value is 'app', setting strict-name-search to true will not return that task in the results, whereas setting it to false will.
        in: query
        name: strict-name-search
        required: false
        schema:
          type: boolean
          description: Flag to toggle on/off strict search mode. When set to true, search by name only will return tasks whose name exactly matches the string value given for the 'name' parameter. When set to false, results will also include tasks whose name contain the string value, but could be longer than the string value itself. For example, if there is a task with the name 'applications', and the search value is 'app', setting strict-name-search to true will not return that task in the results, whereas setting it to false will.
          default: false
      - description: Filters search results whether task is active or not.
        in: query
        name: is-active
        required: false
        schema:
          type: boolean
          description: Filters search results whether task is active or not.
          default: false
      - description: Page number.
        example: 1
        in: query
        name: page
        required: false
        schema:
          type: integer
          description: Page number.
          format: int32
          example: 1
          default: 1
      - description: Page size.
        example: 50
        in: query
        name: page-size
        required: false
        schema:
          minimum: 1
          type: integer
          description: Page size.
          format: int32
          example: 50
          default: 50
      - description: Represents the column as criteria for sorting tasks.
        example: ID
        in: query
        name: sort-column
        required: false
        schema:
          type: string
          enum:
          - ID
          - NAME
      - description: Sorting mode.
        example: ASCENDING
        in: query
        name: sort-order
        required: false
        schema:
          type: string
          enum:
          - ASCENDING
          - DESCENDING
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaskDtoV1'
          description: OK
      summary: Find tasks on a project
      tags:
      - Task
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    post:
      operationId: createTask
      parameters:
      - description: Represents a project identifier across the system.
        example: 25b687e29ae1f428e7ebe123
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
      - description: Flag to set whether task will have assignee or none.
        in: query
        name: contains-assignee
        required: false
        schema:
          type: boolean
          description: Flag to set whether task will have assignee or none.
          default: true
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskRequestV1'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDtoV1'
          description: Created
      summary: Add a new task on a project
      tags:
      - Task
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/projects/{projectId}/tasks/{id}/cost-rate:
    servers:
    - url: https://api.clockify.me/api
    put:
      operationId: setTaskCostRate
      parameters:
      - description: Represents a project identifier across the system.
        example: 25b687e29ae1f428e7ebe123
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a task identifier across the system.
        example: 57a687e29ae1f428e7ebe107
        in: path
        name: id
        required: true
        schema:
          type: string
          description: Represents a task identifier across the system.
          example: 57a687e29ae1f428e7ebe107
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CostRateRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDtoV1'
          description: OK
      summary: Update a task's cost rate
      tags:
      - Task
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/projects/{projectId}/tasks/{id}/hourly-rate:
    servers:
    - url: https://api.clockify.me/api
    put:
      operationId: setTaskHourlyRate
      parameters:
      - description: Represents a project identifier across the system.
        example: 25b687e29ae1f428e7ebe123
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a task identifier across the system.
        example: 57a687e29ae1f428e7ebe107
        in: path
        name: id
        required: true
        schema:
          type: string
          description: Represents a task identifier across the system.
          example: 57a687e29ae1f428e7ebe107
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HourlyRateRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDtoV1'
          description: OK
      summary: Update a task's billable rate
      tags:
      - Task
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
  /v1/workspaces/{workspaceId}/projects/{projectId}/tasks/{taskId}:
    servers:
    - url: https://api.clockify.me/api
    delete:
      operationId: deleteTask
      parameters:
      - description: Represents a task identifier across the system.
        example: 57a687e29ae1f428e7ebe107
        in: path
        name: taskId
        required: true
        schema:
          type: string
          description: Represents a task identifier across the system.
          example: 57a687e29ae1f428e7ebe107
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a project identifier across the system.
        example: 25b687e29ae1f428e7ebe123
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDtoV1'
          description: OK
      summary: Delete a task from a project
      tags:
      - Task
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    get:
      operationId: getTask
      parameters:
      - description: Represents a task identifier across the system.
        example: 57a687e29ae1f428e7ebe107
        in: path
        name: taskId
        required: true
        schema:
          type: string
          description: Represents a task identifier across the system.
          example: 57a687e29ae1f428e7ebe107
      - description: Represents a project identifier across the system.
        example: 25b687e29ae1f428e7ebe123
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDtoV1'
          description: OK
      summary: Get a task by id
      tags:
      - Task
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
    put:
      operationId: updateTask
      parameters:
      - description: Represents a task identifier across the system.
        example: 57a687e29ae1f428e7ebe107
        in: path
        name: taskId
        required: true
        schema:
          type: string
          description: Represents a task identifier across the system.
          example: 57a687e29ae1f428e7ebe107
      - description: Represents a workspace identifier across the system.
        example: 64a687e29ae1f428e7ebe303
        in: path
        name: workspaceId
        required: true
        schema:
          type: string
          description: Represents a workspace identifier across the system.
          example: 64a687e29ae1f428e7ebe303
      - description: Represents a project identifier across the system.
        example: 25b687e29ae1f428e7ebe123
        in: path
        name: projectId
        required: true
        schema:
          type: string
          description: Represents a project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
      - description: Flag to set whether task will have assignee or none.
        in: query
        name: contains-assignee
        required: false
        schema:
          type: boolean
          description: Flag to set whether task will have assignee or none.
          default: true
      - description: Represents a membership status.
        example: ACTIVE
        in: query
        name: membership-status
        required: false
        schema:
          type: string
          enum:
          - PENDING
          - ACTIVE
          - DECLINED
          - INACTIVE
          - ALL
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDtoV1'
          description: OK
      summary: Update a task on a project
      tags:
      - Task
      security:
      - ApiKeyAuth: []
      - AddonKeyAuth: []
components:
  schemas:
    HourlyRateRequestV1:
      required:
      - amount
      type: object
      properties:
        amount:
          minimum: 0
          type: integer
          description: Represents an hourly rate amount as integer.
          format: int32
          example: 20000
        since:
          type: string
          description: Represents a date and time in yyyy-MM-ddThh:mm:ssZ format.
          example: '2020-01-01T00:00:00Z'
    TaskDtoV1:
      type: object
      properties:
        assigneeId:
          type: string
          deprecated: true
        assigneeIds:
          uniqueItems: true
          type: array
          description: Represents list of assignee ids for the task.
          example:
          - 45b687e29ae1f428e7ebe123
          - 67s687e29ae1f428e7ebe678
          items:
            type: string
            description: Represents list of assignee ids for the task.
            example: '["45b687e29ae1f428e7ebe123","67s687e29ae1f428e7ebe678"]'
        billable:
          type: boolean
          description: Indicates whether a task is billable or not.
          default: false
        budgetEstimate:
          type: integer
          description: Represents a task budget estimate as long.
          format: int64
          example: 10000
        costRate:
          $ref: '#/components/schemas/RateDtoV1'
        duration:
          type: string
          description: Represents a task duration.
          example: PT1H30M
        estimate:
          type: string
          description: Represents a task duration estimate.
          example: PT1H30M
        hourlyRate:
          $ref: '#/components/schemas/RateDtoV1'
        id:
          type: string
          description: Represents task identifier across the system.
          example: 57a687e29ae1f428e7ebe107
        name:
          type: string
          description: Represents task name.
          example: Bugfixing
        projectId:
          type: string
          description: Represents project identifier across the system.
          example: 25b687e29ae1f428e7ebe123
        status:
          $ref: '#/components/schemas/TaskStatus'
        userGroupIds:
          uniqueItems: true
          type: array
          description: Represents list of user group ids for the task.
          example:
          - 67b687e29ae1f428e7ebe123
          - 12s687e29ae1f428e7ebe678
          items:
            type: string
            description: Represents list of user group ids for the task.
            example: '["67b687e29ae1f428e7ebe123","12s687e29ae1f428e7ebe678"]'
    CostRateRequestV1:
      required:
      - amount
      type: object
      properties:
        amount:
          minimum: 0
          type: integer
          description: Represents an amount as integer.
          format: int32
          example: 20000
        since:
          type: string
          description: Represents a date and time in yyyy-MM-ddThh:mm:ssZ format.
          example: '2020-01-01T00:00:00Z'
    TaskStatus:
      type: object
      description: Represents task status.
      example: DONE
      oneOf:
      - type: string
        enum:
        - ACTIVE
        - DONE
        - ALL
      properties:
        ACTIVE:
          type: string
          enum:
          - ACTIVE
          - DONE
          - ALL
        ALL:
          type: string
          enum:
          - ACTIVE
          - DONE
          - ALL
        DONE:
          type: string
          enum:
          - ACTIVE
          - DONE
          - ALL
        active:
          type: boolean
    UpdateTaskRequest:
      required:
      - name
      type: object
      properties:
        assigneeId:
          type: string
          deprecated: true
        assigneeIds:
          uniqueItems: true
          type: array
          description: Represents list of assignee ids for the task.
          example:
          - 45b687e29ae1f428e7ebe123
          - 67s687e29ae1f428e7ebe678
          items:
            type: string
            description: Represents list of assignee ids for the task.
            example: '["45b687e29ae1f428e7ebe123","67s687e29ae1f428e7ebe678"]'
        billable:
          type: boolean
          description: Indicates whether a task is billable or not.
          default: false
        budgetEstimate:
          minimum: 0
          type: integer
          description: Represents a task budget estimate as integer.
          format: int64
          example: 10000
        estimate:
          type: string
          description: Represents a task duration estimate.
          example: PT1H30M
        name:
          maxLength: 1000
          minLength: 1
          type: string
          description: Represents task name.
          example: Bugfixing
        status:
          type: string
          description: Represents task status.
          example: DONE
          enum:
          - ACTIVE
          - DONE
          - ALL
        userGroupIds:
          uniqueItems: true
          type: array
          description: Represents list of user group ids for the task.
          example:
          - 67b687e29ae1f428e7ebe123
          - 12s687e29ae1f428e7ebe678
          items:
            type: string
            description: Represents list of user group ids for the task.
            example: '["67b687e29ae1f428e7ebe123","12s687e29ae1f428e7ebe678"]'
    TaskRequestV1:
      required:
      - name
      type: object
      properties:
        assigneeId:
          type: string
          deprecated: true
        assigneeIds:
          uniqueItems: true
          type: array
          description: Represents list of assignee ids for the task.
          example:
          - 45b687e29ae1f428e7ebe123
          - 67s687e29ae1f428e7ebe678
          items:
            type: string
            description: Represents list of assignee ids for the task.
            example: '["45b687e29ae1f428e7ebe123","67s687e29ae1f428e7ebe678"]'
        budgetEstimate:
          minimum: 0
          type: integer
          description: Represents a task budget estimate as long.
          format: int64
          example: 10000
        estimate:
          type: string
          description: Represents a task duration estimate in ISO-8601 format.
          example: PT1H30M
        id:
          type: string
          description: Represents task identifier across the system.
          example: 57a687e29ae1f428e7ebe107
        name:
          maxLength: 1000
          minLength: 1
          type: string
          description: Represents task name.
          example: Bugfixing
        status:
          type: string
          description: Represents task status.
          example: DONE
          enum:
          - ACTIVE
          - DONE
          - ALL
        userGroupIds:
          uniqueItems: true
          type: array
          description: Represents list of user group ids for the task.
          example:
          - 67b687e29ae1f428e7ebe123
          - 12s687e29ae1f428e7ebe678
          items:
            type: string
            description: Represents list of user group ids for the task.
            example: '["67b687e29ae1f428e7ebe123","12s687e29ae1f428e7ebe678"]'
    RateDtoV1:
      type: object
      properties:
        amount:
          type: integer
          description: Represents an amount as integer.
          format: int32
          example: 10500
        currency:
          type: string
          description: Represents a currency.
          example: USD
      description: Represents cost rate object.
  securitySchemes:
    AddonKeyAuth:
      in: header
      name: x-addon-token
      type: apiKey
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey
    MarketplaceKeyAuth:
      in: header
      name: x-marketplace-token
      type: apiKey
    ReportAddonKeyAuth:
      in: header
      name: x-addon-token
      type: apiKey
x-tagGroups:
- name: Clockify API
  tags:
  - User
  - Workspace
  - Webhooks
  - Approval
  - Client
  - Custom fields
  - Expense
  - Holiday
  - Invoice
  - Project
  - Task
  - Scheduling
  - Tag
  - Time entry
  - Balance
  - Policy
  - Time Off
  - Group
- name: Clockify Reports API
  tags:
  - Shared Report
  - Team Report
  - Time Entry Report
  - Expense Report
- name: Clockify Audit Log API
  tags:
  - Audit Log Report
- name: Deprecated API
  tags:
  - Template (Deprecated)
  - Scheduling (Deprecated)
  - Workspace (Deprecated)
- name: Experimental API
  tags:
  - Entity changes (Experimental)
- name: Guide
  tags:
  - 'Entity Changes: Use cases'