Hourtick Tasks API
The task board: tasks (work items), checklist, chat and files. Any member can create and edit.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hourtick:hourtick-tasks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Hourtick Tasks API
version: 1.0.0
description: 'The Hourtick REST API. Authenticate with a personal API token: create one in **Settings → API tokens**, then send `Authorization: Bearer ht_…`.
All timer changes go through **POST /api/v1/commands**, the same endpoint the web and Mac apps use. Commands are idempotent per `commandId` (use a new UUID per action, reuse it to retry safely).
Every response carries a `Server-Time` header (epoch ms). Errors use RFC 9457 problem details.'
servers:
- url: https://hourtick.com
security:
- bearer: []
tags:
- name: Tasks
description: 'The task board: tasks (work items), checklist, chat and files. Any member can create and edit.'
paths:
/api/v1/work-items:
get:
tags:
- Tasks
summary: 'Tasks on the board: open ones plus done in the last 14 days (`done=all` for…'
parameters:
- name: done
in: query
schema:
type: string
enum:
- recent
- all
default: recent
- name: projectId
in: query
schema:
type: string
format: uuid
- name: assigneeId
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/WorkItem'
truncated:
type: boolean
serverTime:
type: integer
operationId: getApiV1WorkItems
x-operation-id-source: derived
post:
tags:
- Tasks
summary: Create a task (any member)
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
title:
type: string
minLength: 1
maxLength: 300
description:
type: string
maxLength: 20000
status:
type: string
enum:
- todo
- in_progress
- review
- done
priority:
type: integer
minimum: 0
maximum: 4
projectId:
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
clientId:
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
dueDate:
type:
- string
- 'null'
estimateSeconds:
anyOf:
- type: integer
minimum: 0
maximum: 36000000
- type: 'null'
parentId:
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
labels:
maxItems: 20
type: array
items:
type: string
minLength: 1
maxLength: 40
assigneeIds:
maxItems: 50
type: array
items:
type: string
minLength: 1
maxLength: 100
required:
- title
additionalProperties: false
example:
title: Design the pricing page
projectId: …
assigneeIds:
- …
priority: 3
dueDate: '2026-10-01'
labels:
- Design
responses:
'201':
description: OK
content:
application/json:
schema:
type: object
properties:
item:
$ref: '#/components/schemas/WorkItem'
'422':
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
operationId: postApiV1WorkItems
x-operation-id-source: derived
/api/v1/work-items/{id}:
get:
tags:
- Tasks
summary: A task with description, checklist, timeline (comments, files, events) and time…
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
'404':
description: Not found
operationId: getApiV1WorkItemsById
x-operation-id-source: derived
patch:
tags:
- Tasks
summary: Update a task.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
title:
type: string
minLength: 1
maxLength: 300
description:
type: string
maxLength: 20000
status:
type: string
enum:
- todo
- in_progress
- review
- done
priority:
type: integer
minimum: 0
maximum: 4
projectId:
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
clientId:
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
dueDate:
type:
- string
- 'null'
estimateSeconds:
anyOf:
- type: integer
minimum: 0
maximum: 36000000
- type: 'null'
parentId:
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
labels:
maxItems: 20
type: array
items:
type: string
minLength: 1
maxLength: 40
assigneeIds:
maxItems: 50
type: array
items:
type: string
minLength: 1
maxLength: 100
position:
type: number
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
item:
$ref: '#/components/schemas/WorkItem'
operationId: patchApiV1WorkItemsById
x-operation-id-source: derived
delete:
tags:
- Tasks
summary: Delete a task with its comments and files (creator or managers).
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Deleted
operationId: deleteApiV1WorkItemsById
x-operation-id-source: derived
/api/v1/work-items/{id}/comments:
get:
tags:
- Tasks
summary: The task's comments, oldest first, with their files (an agent's comment has…
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
'404':
description: Not found
operationId: getApiV1WorkItemsByIdComments
x-operation-id-source: derived
post:
tags:
- Tasks
summary: Post in the task's chat; `attachmentIds` links files you uploaded
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
body:
type: string
maxLength: 10000
attachmentIds:
default: []
maxItems: 20
type: array
items:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
mentionIds:
default: []
maxItems: 50
type: array
items:
type: string
minLength: 1
maxLength: 100
required:
- body
responses:
'201':
description: OK
content:
application/json:
schema:
type: object
operationId: postApiV1WorkItemsByIdComments
x-operation-id-source: derived
/api/v1/work-items/{id}/comments/{commentId}:
patch:
tags:
- Tasks
summary: Edit your comment
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: commentId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
body:
type: string
minLength: 1
maxLength: 10000
required:
- body
responses:
'204':
description: Saved
operationId: patchApiV1WorkItemsByIdCommentsByCommentId
x-operation-id-source: derived
delete:
tags:
- Tasks
summary: Delete a comment and its files (author or managers)
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: commentId
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Deleted
operationId: deleteApiV1WorkItemsByIdCommentsByCommentId
x-operation-id-source: derived
/api/v1/work-items/{id}/checklist:
post:
tags:
- Tasks
summary: Add a checklist item
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
title:
type: string
minLength: 1
maxLength: 500
required:
- title
responses:
'201':
description: OK
content:
application/json:
schema:
type: object
operationId: postApiV1WorkItemsByIdChecklist
x-operation-id-source: derived
/api/v1/work-items/{id}/checklist/{itemId}:
patch:
tags:
- Tasks
summary: Tick, rename or move a checklist item
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: itemId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
title:
type: string
minLength: 1
maxLength: 500
done:
type: boolean
position:
type: number
responses:
'204':
description: Saved
operationId: patchApiV1WorkItemsByIdChecklistByItemId
x-operation-id-source: derived
delete:
tags:
- Tasks
summary: Remove a checklist item
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: itemId
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Deleted
operationId: deleteApiV1WorkItemsByIdChecklistByItemId
x-operation-id-source: derived
/api/v1/work-items/{id}/attachments:
post:
tags:
- Tasks
summary: Upload a file (multipart/form-data, field `file`, up to 25 MB).
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
required:
- file
responses:
'201':
description: OK
content:
application/json:
schema:
type: object
'402':
description: This month's usage is used up; uploads pause until the 1st
'413':
description: File too large
operationId: postApiV1WorkItemsByIdAttachments
x-operation-id-source: derived
/api/v1/attachments/{id}:
get:
tags:
- Tasks
summary: Redirects to a 5-minute signed URL.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'302':
description: Signed URL
operationId: getApiV1AttachmentsById
x-operation-id-source: derived
delete:
tags:
- Tasks
summary: Delete a file (uploader or managers)
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Deleted
operationId: deleteApiV1AttachmentsById
x-operation-id-source: derived
/api/v1/task-views:
get:
tags:
- Tasks
summary: Your saved Tasks views (personal)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
operationId: getApiV1TaskViews
x-operation-id-source: derived
post:
tags:
- Tasks
summary: 'Save a view: people, agents, projects, clients and labels (any-of; `none` for…'
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
name:
type: string
minLength: 1
maxLength: 60
filters:
type: object
properties:
people:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
agents:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
projects:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
clients:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
labels:
maxItems: 50
type: array
items:
type: string
maxLength: 40
q:
type: string
maxLength: 200
layout:
type: string
enum:
- board
- list
additionalProperties: false
required:
- name
- filters
responses:
'201':
description: OK
content:
application/json:
schema:
type: object
operationId: postApiV1TaskViews
x-operation-id-source: derived
/api/v1/task-views/{id}:
patch:
tags:
- Tasks
summary: Rename, move or update a view's filters
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
name:
type: string
minLength: 1
maxLength: 60
filters:
type: object
properties:
people:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
agents:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
projects:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
clients:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
labels:
maxItems: 50
type: array
items:
type: string
maxLength: 40
q:
type: string
maxLength: 200
layout:
type: string
enum:
- board
- list
additionalProperties: false
position:
type: number
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
operationId: patchApiV1TaskViewsById
x-operation-id-source: derived
delete:
tags:
- Tasks
summary: Delete a view
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Deleted
operationId: deleteApiV1TaskViewsById
x-operation-id-source: derived
/api/v1/work-items/{id}/dependencies:
post:
tags:
- Tasks
summary: Mark this task blocked by another (type blocked_by) or blocking another (type…
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
type:
type: string
enum:
- blocked_by
- blocks
workItemId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required:
- type
- workItemId
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
operationId: postApiV1WorkItemsByIdDependencies
x-operation-id-source: derived
delete:
tags:
- Tasks
summary: Remove the dependency; a task with no open blockers left unlocks
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
type:
type: string
enum:
- blocked_by
- blocks
workItemId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required:
- type
- workItemId
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
operationId: deleteApiV1WorkItemsByIdDependencies
x-operation-id-source: derived
components:
schemas:
Problem:
type: object
properties:
type:
type: string
title:
type: string
status:
type: integer
detail:
type: string
entry:
$ref: '#/components/schemas/TimeEntry'
conflicts:
type: array
description: 'Bulk edits: entries that blocked the change.'
items:
type: object
properties:
id:
type: string
reason:
type: string
WorkItem:
type: object
description: 'A task. Status: todo | in_progress | review | done. Priority: 0 none … 4 urgent. `description` (in the detail and in writes) is Markdown, including `- [ ]` checklists.'
properties:
id:
type: string
format: uuid
number:
type: integer
description: 'Short number shown as #12'
title:
type: string
status:
type: string
enum:
- todo
- in_progress
- review
- done
priority:
type: integer
minimum: 0
maximum: 4
projectId:
type:
- string
- 'null'
clientId:
type:
- string
- 'null'
dueDate:
type:
- string
- 'null'
format: date
estimateSeconds:
type:
- integer
- 'null'
labels:
type: array
items:
type: string
position:
type: number
assigneeIds:
type: array
items:
type: string
trackedSeconds:
type: integer
runningUserIds:
type: array
items:
type: string
commentCount:
type: integer
attachmentCount:
type: integer
checklistDone:
type: integer
checklistTotal:
type: integer
TimeEntry:
type: object
properties:
id:
type: string
format: uuid
workspaceId:
type: string
format: uuid
userId:
type: string
projectId:
type: string
format: uuid
taskId:
type: string
format: uuid
description: Task type
workItemId:
type:
- string
- 'null'
format: uuid
description: The task this time is for, if any
notes:
type: string
spentDate:
type: string
format: date
description: The day the time belongs to (user's time zone).
timezone:
type: string
examples:
- Europe/Copenhagen
accumulatedSeconds:
type: integer
description: Seconds banked from completed runs.
timerStartedAt:
type:
- integer
- 'null'
description: Epoch ms when the current run started; null when stopped.
billable:
type: boolean
lockedReason:
type:
- string
- 'null'
enum:
- null
- invoiced
- approved
- submitted
version:
type: integer
deletedAt:
type:
- integer
- 'null'
createdAt:
type: integer
updatedAt:
type: integer
description: Live duration = accumulatedSeconds + (now − timerStartedAt)/1000 while running.
securitySchemes:
bearer:
type: http
scheme: bearer
bearerFormat: ht_… personal API token