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": "open",
  "snoozed_until": null,
  "snoozed_by": null,
  "created_at": "2021-08-19T06:34:16+00:00",
  "messages_count": 1,
  "latest_message": {}
}
1
2
3
4
5
6
7
8
9
10
11
12

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 open, closed or snoozed.


snoozed_until string|null

The datetime when the Project's status will be changed to open. Present only if the status is snoozed.


snoozed_by string|null

The User who snoozed the Project. Present only if the status is snoozed.


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.




List Projects

GET /v1/projects

curl 'https://{workspace}.kitchen.co/api/v1/projects' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer {AUTH_TOKEN}'
1
2
3

Response

{
  "data": [
    {
      "id": "1",
      "author": {},
      "company": null,
      "title": "Acme - website redesign",
      "status": "open",
      "snoozed_until": null,
      "snoozed_by": null,
      "created_at": "2021-08-19T06:34:16+00:00",
      "messages_count": 1,
      "latest_message": {}
    },],
  "meta": {}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20



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}'
1
2
3

Parameters

project_id string required

The id of the Project.


Response

{
  "id": "1",
  "author": {},
  "company": null,
  "title": "Acme - website redesign",
  "status": "open",
  "snoozed_until": null,
  "snoozed_by": null,
  "created_at": "2021-08-19T06:34:16+00:00",
  "messages_count": 1,
  "latest_message": {}
}
1
2
3
4
5
6
7
8
9
10
11
12



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[][email protected]"attachment.jpg"' \
 -F 'custom_fields[Project Type]="design"' \
 -X POST
1
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": "open",
  "snoozed_until": null,
  "snoozed_by": null,
  "created_at": "2021-08-19T06:34:16+00:00",
  "messages_count": 1,
  "latest_message": {}
}
1
2
3
4
5
6
7
8
9
10
11
12



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
1
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": "open",
  "snoozed_until": null,
  "snoozed_by": null,
  "created_at": "2021-08-19T06:34:16+00:00",
  "messages_count": 1,
  "latest_message": {}
}
1
2
3
4
5
6
7
8
9
10
11
12



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
1
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,
}
1
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
1
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
1
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,
}
1
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
1
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