Projects
The Projects API lets you create, list and update projects in a Workspace.
The Project object
{
"id": "1",
"author": {…},
"company": null,
"title": "Acme - website redesign",
"status": "active",
"created_at": "2021-08-19T06:34:16+00:00",
"messages_count": 1,
"latest_message": {…},
"custom_fields": […]
}
2
3
4
5
6
7
8
9
10
11
Attributes
id string
The unique identifier of the Project.
author User
The User who created the Project. See The User object.
company Company|null
The Company associated with the Project. Present if the Project is owned by a Company. See The Company object.
title string
The title of the Project.
status string
The status of the Project. Can be active or archived.
created_at string
The creation datetime of the Project.
messages_count int
The number of the Messages in the Project.
latest_message Message
The latest message that has been posted in the Project. See The Message object.
custom_fields array
The custom fields used in the Project. See The Custom Field object.
List Projects
GET /v1/projects
curl 'https://{workspace}.kitchen.co/api/v1/projects' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}'
2
3
Response
{
"data": [
{
"id": "1",
"author": {…},
"company": null,
"title": "Acme - website redesign",
"status": "active",
"created_at": "2021-08-19T06:34:16+00:00",
"messages_count": 1,
"latest_message": {…}
},
…
],
"meta": {
…
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Retrieve a Project
GET /v1/projects/{project_id}
curl 'https://{workspace}.kitchen.co/api/v1/projects/{project_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}'
2
3
Parameters
project_id string required
The id of the Project.
Response
{
"id": "1",
"author": {…},
"company": null,
"title": "Acme - website redesign",
"status": "active",
"created_at": "2021-08-19T06:34:16+00:00",
"messages_count": 1,
"latest_message": {…},
"custom_fields": […]
}
2
3
4
5
6
7
8
9
10
11
Create a Project
POST /v1/projects
curl 'https://{workspace}.kitchen.co/api/v1/projects' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
-F 'title="New project"' \
-F 'name="John Doe"' \
-F 'email="[email protected]"' \
-F 'initial_message="Lorem Ipsum Dolor Sit Amet"' \
-F 'initial_message_format="markdown"' \
-F 'files[]=@"attachment.jpg"' \
-F 'custom_fields[Project Type]="design"' \
-X POST
2
3
4
5
6
7
8
9
10
11
Body parameters
title string required
The title of the Project.
name string required
The name of the author of the Project.
email string required
The email of the author of the Project. If the User doesn't exists it will be created.
initial_message string required
The initial Message of the Project.
initial_message_format string required
The initial Message format of the Project. See The Message object.
files string[] optional
File urls that will be attached to the initial Message of the Project.
custom_fields string[] optional
The Custom Fields that will be populated in the Project. The custom fields should exist in the Workspace, when a non-existing custom field is passed, it's value is not saved. Note that the custom field name is case-sensitive.
Response
{
"id": "1",
"author": {…},
"company": null,
"title": "Acme - website redesign",
"status": "active",
"created_at": "2021-08-19T06:34:16+00:00",
"messages_count": 1,
"latest_message": {…}
}
2
3
4
5
6
7
8
9
10
Update a Project
PUT /v1/projects/{project_id}
curl 'https://{workspace}.kitchen.co/api/v1/projects/{project_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
-d 'title=New project title' \
-X PUT
2
3
4
5
Parameters
project_id string required
The id of the Project.
Body parameters
title string
The new title of the Project.
Response
{
"id": "1",
"author": {…},
"company": null,
"title": "New project title",
"status": "active",
"created_at": "2021-08-19T06:34:16+00:00",
"messages_count": 1,
"latest_message": {…}
}
2
3
4
5
6
7
8
9
10
Add a Client to a Project
PUT /v1/projects/{project_id}/clients
curl 'http://{workspace}.kitchen.co/api/v1/projects/{project_id}/clients' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
-d 'user_id=1' \
-X PUT
2
3
4
5
Note that the client will receive a notification for project invitation; the inviter will be the manager whose API key is used in the API request.
Parameters
project_id string Required
The id of the Project.
Body parameters
user_id string required
The id of the User. Should be a client User.
Response
{
"id": "1",
"added_on": "2021-10-26T12:02:44+00:00",
"name": "John Doe",
"email": "[email protected]",
"username": "johndoe",
"phone": "012345678",
"timezone": null,
"group": "client",
"role": "member",
"avatar_type": null,
"avatar_url": null,
"avatar_gravatar_url": null,
"avatar_file": null,
"color": "#32abfe",
"default_color": "#32abfe",
"is_active": true,
"last_seen": null,
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Remove a Client from a Project
DELETE /v1/projects/{project_id}/clients/{client_id}
curl 'http://{workspace}.kitchen.co/api/v1/projects/{project_id}/clients/{client_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
-X DELETE
2
3
4
Parameters
project_id string required
The id of the Project.
client_id string required
The id of the client User.
Response
Status 204 No Content
Add a Manager to a Project
PUT /v1/projects/{project_id}/managers
curl 'http://{workspace}.kitchen.co/api/v1/projects/{project_id}/managers' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
-d 'user_id=3' \
-X PUT
2
3
4
5
Parameters
project_id string Required
The id of the Project.
Body parameters
user_id string required
The id of the User. Should be a manager User.
Response
{
"id": "3",
"added_on": "2021-10-26T12:02:44+00:00",
"name": "John Doe",
"email": "[email protected]",
"username": "johndoe",
"phone": "012345678",
"timezone": null,
"group": "manager",
"role": "admin",
"avatar_type": null,
"avatar_url": null,
"avatar_gravatar_url": null,
"avatar_file": null,
"color": "#32abfe",
"default_color": "#32abfe",
"is_active": true,
"last_seen": null,
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Remove a Manager from a Project
DELETE /v1/projects/{project_id}/managers/{manager_id}
curl 'http://{workspace}.kitchen.co/api/v1/projects/{project_id}/managers/{manager_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
-X DELETE
2
3
4
Parameters
project_id string required
The id of the Project.
manager_id string required
The id of the manager User.
Response
Status 204 No Content
The Custom Field object
{
"id": "1",
"name": "Custom Field Title",
"type": "text",
"options": [...],
"description": "Custom Field Description",
"field_name": "custom_field_text",
"scope": "project",
"value": {
"id": "1.1",
"native_type": "string",
"value": "Custom Field Value",
},
"created_at": "2021-08-19T06:34:16+00:00",
"updated_at": "2021-08-19T06:34:16+00:00"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Attributes
id string
The unique identifier of the Custom Field.
name string
The name of the Custom Field.
type string
The type of the Custom Field. Can be text, number, boolean, date and list.
options array|null
The options of the Custom Field when list type is used.
description string
The description of the Custom Field.
field_name string
The status of the Project. Can be open, closed or snoozed.
scope string
The scope of the Project. Defaults to project.
value object
Object representation of the Custom Field value.
value.id string
The unique identifier of the Custom Field value.
value.native_type string
The native type of the Custom Field. Can be string, int, date and bool.
value.value string
String representation of the Custom Field value.
created_at string
The creation datetime of the Custom Field.
updated_at string
The update datetime of the Custom Field.