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": []
}
1
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}'
1
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": {}
}
1
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}'
1
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": []
}
1
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[][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": "active",
  "created_at": "2021-08-19T06:34:16+00:00",
  "messages_count": 1,
  "latest_message": {}
}
1
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
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": "active",
  "created_at": "2021-08-19T06:34:16+00:00",
  "messages_count": 1,
  "latest_message": {}
}
1
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
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

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"
}
1
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.