Clockify Project API
The Project API from Clockify — 8 operation(s) for project.
The Project API from Clockify — 8 operation(s) for project.
openapi: 3.0.1
info:
description: "## Introduction\nBy using this REST API, you can easily integrate Clockify with your own add-ons, push and pull data\nbetween Clockify and other tools, and create custom add-ons on [CAKE.com Marketplace](https://marketplace.cake.com).\nWhether you’re looking to automate time tracking, generate custom reports, or build other custom\nintegrations, our API provides the flexibility and power you need to get the job done. If you\nhave any questions or run into any issues while using our API, don’t hesitate to reach out to us for help.\nYou can also post questions on Stack Overflow with the Clockify tag to get help from the community.\n## Authentication\nTo authenticate your requests to your API, make sure to include either the ‘X-Api-Key’ or the\n‘X-Addon-Token’ in the request header, containing your API or Addon key. If your workspace is\non a subdomain (e.g. subdomain.clockify.me), you’ll need to generate a new API key in your\nProfile Settings that will work specifically for that workspace. This ensures that you’re\naccessing data from the correct workspace and helps maintain the security of your data.\n## Webhooks\nWebhooks can enhance your workflow by keeping your add-on up-to-date with the latest changes in\nClockify. With Clockify’s webhooks you can receive real-time notifications when certain events such as\nstarting a timer or deleting a time entry occur in Clockify.\nDepending on the workspace plan, workspace owners and admins can create:\n\n* Up to 3 webhooks on **FREE** plan\n* Up to 10 webhooks per user, with a total of 100 webhooks per entire workspace\non **BASIC**, **STANDARD** and **PRO** plans\n* Up to 100 webhooks per user, with a total of 300 webhooks per entire workspace on **ENTERPRISE** plan\n\n## Rate limiting\nOur REST API has a specific rate limit of 50 requests per second (by addon on one workspace) when\naccessed using X-Addon-Token. Exceeding this limit will result in an error message with the description\n\"Too many requests\".\n## Pagination\nOur REST API supports pagination for all synchronous GET endpoints that retrieve lists of entities.\nWhen an endpoint accepts the `page` and `pageSize` query parameters, it will return a paginated response.\n\nTo control the data returned in a paginated request, you can use the following optional query parameters.\n\n- **page** (integer): The page number you wish to retrieve. This is 1-indexed. If this parameter is omitted,\nthe API will default to the first page (page=1).\n- **pageSize** (integer): The number of items to include on each page. If this parameter is omitted,\na default page size will be used.\n\nEvery response from an endpoint that supports these parameters will include a custom `Last-Page` header.\nThis header provides a simple way to determine if you have reached the end of the data set.\n\n- **true:** The current page is the final page; no more data is available.\n- **false:** Additional pages can be fetched.\n## API URLs\nRefer to the list on what URL to use base on the subdomain and data region settings of your workspace.\n* Global - can be used by workspaces with or without subdomain.\n * Regular: https://api.clockify.me/api/v1/file/image\n * Reports: https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/detailed\n* Regional\n * Non-subdomain\n * Regular: https://euc1.clockify.me/api/v1/file/image\n * Reports: https://use2.clockify.me/report/v1/workspaces/{workspaceId}/reports/detailed\n * Subdomain\n * Regular: https://euc1.clockify.me/api/v1/file/image\n * Reports: https://yoursubdomainname.clockify.me/report/v1/workspaces/{workspaceId}/reports/detailed\n* Developer\n * Regular: https://developer.clockify.me/api/v1/file/image\n * Reports: https://developer.clockify.me/report/v1/workspaces/{workspaceId}/reports/detailed\n## Regional Server Prefixes\nIf your workspace is in a specific region, you need to change your URL prefix to access v1 API endpoints.\nFor example, this is how **backend** api [v1/file/image](#tag/User/operation/uploadImage) endpoint\nwould look in EU region:\n[https://euc1.clockify.me/api/v1/file/image](https://euc1.clockify.me)\n\nBelow are the available regional server prefixes:\n* **EU (Germany)**: euc1\n* **USA**: use2\n* **UK**: euw2\n* **AU**: apse2\n\n\n## Breaking changes\nBreaking changes in APIs are modifications that disrupt existing integrations,\nrequiring users to update their applications to maintain functionality.\nThese changes can lead to failures or unexpected results if not addressed.\nSee the list of [breaking changes](breaking-changes/).\n\n## Experimental APIs\nThe experimental API has been thoroughly tested and is ready for use in production. However, please note that user feedback may lead to changes in the API’s structure or functionality. If you choose to use the experimental API, be prepared to modify your application code accordingly to accommodate any updates."
title: Clockify Approval Project API
version: v1
x-logo:
altText: Clockify logo
url: https://clockify.me/downloads/clockify_logo_primary_black_margin.png
tags:
- name: Project
x-displayName: Project
paths:
/v1/workspaces/{workspaceId}/projects:
servers:
- url: https://api.clockify.me/api
get:
operationId: getProjects
parameters:
- 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 projects that contains the provided string in the project name.
example: Software Development
in: query
name: name
required: false
schema:
type: string
description: If provided, you'll get a filtered list of projects that contains the provided string in the project name.
example: Software Development
- description: Flag to toggle on/off strict search mode. When set to true, search by name will only return projects whose name exactly matches the string value given for the 'name' parameter. When set to false, results will also include projects whose name contain the string value, but could be longer than the string value itself. For example, if there is a project with the name 'applications', and the search value is 'app', setting strict-name-search to true will not return that project 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 will only return projects whose name exactly matches the string value given for the 'name' parameter. When set to false, results will also include projects whose name contain the string value, but could be longer than the string value itself. For example, if there is a project with the name 'applications', and the search value is 'app', setting strict-name-search to true will not return that project in the results, whereas setting it to false will.
default: false
- description: If provided and set to true, you'll only get archived projects. If omitted, you'll get both archived and non-archived projects.
in: query
name: archived
required: false
schema:
type: boolean
description: If provided and set to true, you'll only get archived projects. If omitted, you'll get both archived and non-archived projects.
default: false
- description: If provided and set to true, you'll only get billable projects. If omitted, you'll get both billable and non-billable projects.
in: query
name: billable
required: false
schema:
type: boolean
description: If provided and set to true, you'll only get billable projects. If omitted, you'll get both billable and non-billable projects.
default: false
- description: If provided, you'll get a filtered list of projects that contain clients which match any of the provided ids.
example:
- 5a0ab5acb07987125438b60f
- 64c777ddd3fcab07cfbb210c
in: query
name: clients
required: false
schema:
uniqueItems: true
type: array
description: If provided, you'll get a filtered list of projects that contain clients which match any of the provided ids.
example:
- 5a0ab5acb07987125438b60f
- 64c777ddd3fcab07cfbb210c
items:
type: string
description: If provided, you'll get a filtered list of projects that contain clients which match any of the provided ids.
example: '["5a0ab5acb07987125438b60f","64c777ddd3fcab07cfbb210c"]'
- description: If set to true, you'll get a filtered list of projects that contain clients which match the provided id(s) in 'clients' field. If set to false, you'll get a filtered list of projects which do NOT contain clients that match the provided id(s) in 'clients' field.
in: query
name: contains-client
required: false
schema:
type: boolean
description: If set to true, you'll get a filtered list of projects that contain clients which match the provided id(s) in 'clients' field. If set to false, you'll get a filtered list of projects which do NOT contain clients that match the provided id(s) in 'clients' field.
default: true
- description: Filters projects based on client status provided.
example: ACTIVE
in: query
name: client-status
required: false
schema:
type: string
enum:
- ACTIVE
- ARCHIVED
- ALL
- description: If provided, you'll get a filtered list of projects that contain users which match any of the provided ids.
example:
- 5a0ab5acb07987125438b60f
- 64c777ddd3fcab07cfbb210c
in: query
name: users
required: false
schema:
uniqueItems: true
type: array
description: If provided, you'll get a filtered list of projects that contain users which match any of the provided ids.
example:
- 5a0ab5acb07987125438b60f
- 64c777ddd3fcab07cfbb210c
items:
type: string
description: If provided, you'll get a filtered list of projects that contain users which match any of the provided ids.
example: '["5a0ab5acb07987125438b60f","64c777ddd3fcab07cfbb210c"]'
- description: If set to true, you'll get a filtered list of projects that contain users which match the provided id(s) in 'users' field. If set to false, you'll get a filtered list of projects which do NOT contain users which match the provided id(s) in 'users' field.
in: query
name: contains-user
required: false
schema:
type: boolean
description: If set to true, you'll get a filtered list of projects that contain users which match the provided id(s) in 'users' field. If set to false, you'll get a filtered list of projects which do NOT contain users which match the provided id(s) in 'users' field.
default: true
- description: Filters projects based on user status provided.
example: ALL
in: query
name: user-status
required: false
schema:
type: string
enum:
- PENDING
- ACTIVE
- DECLINED
- INACTIVE
- ALL
- description: Filters projects based on whether they are used as a template or not.
in: query
name: is-template
required: false
schema:
type: boolean
description: Filters projects based on whether they are used as a template or not.
default: false
- description: Sorts the results by the given column/field.
example: NAME
in: query
name: sort-column
required: false
schema:
type: string
enum:
- ID
- NAME
- CLIENT_NAME
- DURATION
- BUDGET
- PROGRESS
- description: Sorting mode.
example: ASCENDING
in: query
name: sort-order
required: false
schema:
type: string
enum:
- ASCENDING
- DESCENDING
- description: If set to true, results will contain additional information about the project.
in: query
name: hydrated
required: false
schema:
type: boolean
description: If set to true, results will contain additional information about the project.
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: Valid set of string(s). If provided, you'll get a filtered list of projects that matches the provided access.
example: PUBLIC
in: query
name: access
required: false
schema:
type: string
enum:
- PUBLIC
- PRIVATE
- description: Represents the maximum number of expenses to fetch.
example: 10
in: query
name: expense-limit
required: false
schema:
type: integer
description: Represents the maximum number of expenses to fetch.
format: int32
example: 10
default: 20
- description: If provided, you will get expenses dated before the provided value in yyyy-MM-dd format.
example: '2024-12-31'
in: query
name: expense-date
required: false
schema:
type: string
description: If provided, you will get expenses dated before the provided value in yyyy-MM-dd format.
example: '2024-12-31'
- description: If provided, you'll get a filtered list of projects that contain groups which match any of the provided ids.
example:
- 5a0ab5acb07987125438b60f
- 64c777ddd3fcab07cfbb210c
in: query
name: userGroups
required: false
schema:
uniqueItems: true
type: array
description: If provided, you'll get a filtered list of projects that contain groups which match any of the provided ids.
example:
- 5a0ab5acb07987125438b60f
- 64c777ddd3fcab07cfbb210c
items:
type: string
description: If provided, you'll get a filtered list of projects that contain groups which match any of the provided ids.
example: '["5a0ab5acb07987125438b60f","64c777ddd3fcab07cfbb210c"]'
- description: If set to true, you'll get a filtered list of projects that contain groups which match the provided id(s) in 'userGroups' field. If set to false, you'll get a filtered list of projects which do NOT contain groups which match the provided id(s) in 'userGroups' field.
in: query
name: contains-group
required: false
schema:
type: boolean
description: If set to true, you'll get a filtered list of projects that contain groups which match the provided id(s) in 'userGroups' field. If set to false, you'll get a filtered list of projects which do NOT contain groups which match the provided id(s) in 'userGroups' field.
default: true
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProjectDtoV1'
description: OK
summary: Get all projects on a workspace
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
post:
operationId: createNewProject
parameters:
- 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/ProjectRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: Created
summary: Add a new project
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
/v1/workspaces/{workspaceId}/projects/from-template:
servers:
- url: https://api.clockify.me/api
post:
operationId: createProjectFromTemplate
parameters:
- 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/CreateProjectFromTemplateV1'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Create project from a template
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
/v1/workspaces/{workspaceId}/projects/{projectId}:
servers:
- url: https://api.clockify.me/api
delete:
operationId: deleteProject
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Delete a project from a workspace
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
get:
operationId: getProject
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
- description: If set to true, results will contain additional information about the project
in: query
name: hydrated
required: false
schema:
type: boolean
description: If set to true, results will contain additional information about the project
default: false
- description: If provided, you'll get a filtered list of custom fields that matches the provided string with the custom field entity type.
example: TIMEENTRY
in: query
name: custom-field-entity-type
required: false
schema:
type: string
default: TIMEENTRY
- description: Represents the maximum number of expenses to fetch.
example: 10
in: query
name: expense-limit
required: false
schema:
type: integer
description: Represents the maximum number of expenses to fetch.
format: int32
example: 10
default: 20
- description: If provided, you will get expenses dated before the provided value in yyyy-MM-dd format.
example: '2024-12-31'
in: query
name: expense-date
required: false
schema:
type: string
description: If provided, you will get expenses dated before the provided value in yyyy-MM-dd format.
example: '2024-12-31'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoV1'
description: OK
summary: Find a project by ID
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
put:
operationId: updateProject
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProjectRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Update a project on a workspace
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
/v1/workspaces/{workspaceId}/projects/{projectId}/estimate:
servers:
- url: https://api.clockify.me/api
patch:
operationId: updateEstimate
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectEstimateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Update project estimate
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
/v1/workspaces/{workspaceId}/projects/{projectId}/memberships:
servers:
- url: https://api.clockify.me/api
patch:
operationId: updateMemberships
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProjectMembershipsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Update project memberships
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
post:
operationId: addUsersToProject
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddUsersToProjectRequestV1'
required: true
responses:
'200':
content:
'*/*':
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Assign/remove users to/from the project
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
/v1/workspaces/{workspaceId}/projects/{projectId}/template:
servers:
- url: https://api.clockify.me/api
patch:
operationId: updateIsProjectTemplate
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchProjectTemplateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Update a project template
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
/v1/workspaces/{workspaceId}/projects/{projectId}/users/{userId}/cost-rate:
servers:
- url: https://api.clockify.me/api
put:
operationId: addUsersCostRate
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
- description: Represents a user identifier across the system.
example: 4a0ab5acb07987125438b60f
in: path
name: userId
required: true
schema:
type: string
description: Represents a user identifier across the system.
example: 4a0ab5acb07987125438b60f
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CostRateRequestV1'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Update project user's cost rate
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
/v1/workspaces/{workspaceId}/projects/{projectId}/users/{userId}/hourly-rate:
servers:
- url: https://api.clockify.me/api
put:
operationId: addUsersHourlyRate
parameters:
- 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: 5b641568b07987035750505e
in: path
name: projectId
required: true
schema:
type: string
description: Represents a project identifier across the system.
example: 5b641568b07987035750505e
- description: Represents a user identifier across the system.
example: 4a0ab5acb07987125438b60f
in: path
name: userId
required: true
schema:
type: string
description: Represents a user identifier across the system.
example: 4a0ab5acb07987125438b60f
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CostRateRequestV1'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDtoImplV1'
description: OK
summary: Update a project user's billable rate
tags:
- Project
security:
- ApiKeyAuth: []
- AddonKeyAuth: []
components:
schemas:
PatchProjectTemplateRequest:
type: object
properties:
isTemplate:
type: boolean
description: Indicates whether project is a template or not.
default: false
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'
ProjectRequest:
req
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clockify/refs/heads/main/openapi/clockify-project-api-openapi.yml