NAV
API Version:
shell

Clubhouse API

Introduction

The Clubhouse API provides a greater amount of control over your organization’s Clubhouse data than what is possible using the Clubhouse web app. You can use this API to build custom integrations or automate even more of your organization’s workflow. If you have any questions about anything related to our API or this documentation, please let us know - we’re happy to help!

API Status

This is v1, the latest stable version of our API. If you’re building a library, we recommend using v1. If you’re looking for newer features or don’t mind living on the edge, check out our beta version.

Several open-source libraries that use our API already exist and are listed on our Developers page.

Authentication

API URL

https://api.clubhouse.io/

The Clubhouse API uses token-based authentication. To generate an API token, go to https://app.clubhouse.io/settings/account/api-tokens. To make it easier to explore our API, we recommend saving this token as an environment variable in your local dev environment:

export CLUBHOUSE_API_TOKEN="YOUR API TOKEN HERE"

This will allow you to copy and paste many of the example curl requests on this page into your terminal to try them out.

Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS. Tokens provide complete access to your Clubhouse account, so keep them secure. Don’t paste them into your source code, use an environment variable instead. For security reasons, we will immediately invalidate any tokens we find have been made public.

Response Formats

We respond with JSON by default, however you can request data in CSV format by using a Accept: text/csv request header instead of Content-Type: application/json. See our endpoint documentation below for example requests using curl.

Nullable Fields

Some optional parameters accept a null value, which effectively unsets or deletes the property. For example, you can estimate a story as 1, and then later on remove the estimate by using null.

Change Log

Version 1.0

June 27, 2016

Changes:

June 17, 2016

Changes:

June 1, 2016

Changes:

April, 4 2016

Deletions:

Epics

Get Epic

Get Epic returns information about the selected Epic.

Definition

GET https://api.clubhouse.io/api/v1/epics/{epic-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/epics/{epic-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "deadline": "2016-12-31T12:30:00Z",
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "text": "foo",
    "deleted": true,
    "id": 123,
    "comments": [Recursive]
  }],
  "archived": true,
  "description": "foo",
  "state": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123
}

URL Parameters

Name Description
epic-public-id Integer Required. The unique ID of the Epic.

Responses

Code Description
200 Epic
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Epic

Update Epic can be used to update numerous fields in the Epic. The only required parameter is Epic ID, which can be found in the Clubhouse UI.

Definition

PUT https://api.clubhouse.io/api/v1/epics/{epic-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "before_id": 123, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "deadline": "2016-12-31T12:30:00Z", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "archived": true, "description": "foo", "state": "in progress", "after_id": 123 }' \
  -L "https://api.clubhouse.io/api/v1/epics/{epic-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "deadline": "2016-12-31T12:30:00Z",
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "text": "foo",
    "deleted": true,
    "id": 123,
    "comments": [Recursive]
  }],
  "archived": true,
  "description": "foo",
  "state": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123
}

URL Parameters

Name Description
epic-public-id Integer Required. The unique ID of the Epic.

Body Parameters

Name Description
after_id Integer The ID of the Epic we want to move this Epic after.
archived Boolean A true/false boolean indicating whether the Epic is in archived state.
before_id Integer The ID of the Epic we want to move this Epic before.
deadline Date or null The Epic’s deadline.
description String The Epic’s description.
follower_ids Array [UUID] An array of UUIDs for any Users you want to add as Followers on this Epic.
name String The Epic’s name.
owner_ids Array [UUID] An array of UUIDs for any users you want to add as Owners on this Epic.
state Enum (in progress, to do, done) The Epic’s state (to do, in progress, or done).

Responses

Code Description
200 Epic
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Epic

Delete Epic can be used to delete the Epic. The only required parameter is Epic ID.

Definition

DELETE https://api.clubhouse.io/api/v1/epics/{epic-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/epics/{epic-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
epic-public-id Integer Required. The ID of the Epic to be deleted.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Epics

List Epics returns a list of all Epics and their attributes.

Definition

GET https://api.clubhouse.io/api/v1/epics

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/epics?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "deadline": "2016-12-31T12:30:00Z",
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "comments": [{
      "author_id": "12345678-9012-3456-7890-123456789012",
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "text": "foo",
      "deleted": true,
      "id": 123,
      "comments": [Recursive]
    }],
    "archived": true,
    "description": "foo",
    "state": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": 123
  }
]

Responses

Code Description
200 [ Epic, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Epic

Create Epic allows you to create a new Epic in Clubhouse.

Definition

POST https://api.clubhouse.io/api/v1/epics

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "follower_ids": ["12345678-9012-3456-7890-123456789012"], "deadline": "2016-12-31T12:30:00Z", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "description": "foo", "state": "in progress", "created_at": "2016-12-31T12:30:00Z", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z" }' \
  -L "https://api.clubhouse.io/api/v1/epics?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "deadline": "2016-12-31T12:30:00Z",
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "text": "foo",
    "deleted": true,
    "id": 123,
    "comments": [Recursive]
  }],
  "archived": true,
  "description": "foo",
  "state": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123
}

Body Parameters

Name Description
created_at Date Defaults to the time it is created but can be set to reflect another date.
deadline Date or null The Epic’s deadline.
description String The Epic’s description.
external_id String This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any Users you want to add as Followers on this new Epic.
name String Required. The Epic’s name.
owner_ids Array [UUID] An array of UUIDs for any users you want to add as Owners on this new Epic.
state Enum (in progress, to do, done) The Epic’s state (to do, in progress, or done).
updated_at Date Defaults to the time it is created but can be set to reflect another date.

Responses

Code Description
201 Epic
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Files

Get File

Get File returns information about the selected File.

Definition

GET https://api.clubhouse.io/api/v1/files/{file-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/files/{file-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "name": "foo",
  "thumbnail_url": "foo",
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "size": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "story_ids": [123],
  "content_type": "foo",
  "filename": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "url": "foo",
  "id": 123
}

URL Parameters

Name Description
file-public-id Integer Required. The File’s unique ID.

Responses

Code Description
200 File
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update File

Update File can used to update the properties of a file uploaded to Clubhouse.

Definition

PUT https://api.clubhouse.io/api/v1/files/{file-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "created_at": "2016-12-31T12:30:00Z", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "uploader_id": "12345678-9012-3456-7890-123456789012", "name": "foo", "description": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/files/{file-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "name": "foo",
  "thumbnail_url": "foo",
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "size": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "story_ids": [123],
  "content_type": "foo",
  "filename": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "url": "foo",
  "id": 123
}

URL Parameters

Name Description
file-public-id Integer Required. The unique ID assigned to the file in Clubhouse.

Body Parameters

Name Description
created_at Date The time/date that the file was uploaded.
description String The description of the file.
external_id String An additional ID that you may wish to assign to the file.
name String The name of the file.
updated_at Date The time/date that the file was last updated.
uploader_id UUID The unique ID assigned to the User who uploaded the file to Clubhouse.

Responses

Code Description
200 File
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete File

Delete File can be used to delete any previously attached File.

Definition

DELETE https://api.clubhouse.io/api/v1/files/{file-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/files/{file-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
file-public-id Integer Required. The ID of the file you wish to delete.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Files

List Files returns a list of all Files and related attributes in your Clubhouse.

Definition

GET https://api.clubhouse.io/api/v1/files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/files?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "thumbnail_url": "foo",
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "description": "foo",
    "size": 123,
    "created_at": "2016-12-31T12:30:00Z",
    "story_ids": [123],
    "content_type": "foo",
    "filename": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo",
    "id": 123
  }
]

Responses

Code Description
200 [ File, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Labels

List Labels

List Labels returns a list of all Labels and their attributes.

Definition

GET https://api.clubhouse.io/api/v1/labels

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/labels?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "num_stories_in_progress": 123,
    "num_stories_total": 123,
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_stories_completed": 123,
    "id": 123
  }
]

Responses

Code Description
200 [ LabelWithCounts, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Label

Create Label allows you to create a new Label in Clubhouse.

Definition

POST https://api.clubhouse.io/api/v1/labels

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "foo", "name": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/labels?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "num_stories_in_progress": 123,
  "num_stories_total": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "num_stories_completed": 123,
  "id": 123
}

Body Parameters

Name Description
external_id String This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
name String Required. The name of the new Label.

Responses

Code Description
201 LabelWithCounts
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Label

Update Label allows you to replace a Label name with another name. If you try to name a Label something that already exists, you will receive a 422 response.

Definition

PUT https://api.clubhouse.io/api/v1/labels/{label-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "name": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/labels/{label-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "num_stories_in_progress": 123,
  "num_stories_total": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "num_stories_completed": 123,
  "id": 123
}

URL Parameters

Name Description
label-public-id Integer Required. The unique ID of the Label you wish to update.

Body Parameters

Name Description
name String Required. The new name of the label.

Responses

Code Description
200 LabelWithCounts
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Label

Delete Label can be used to delete any Label.

Definition

DELETE https://api.clubhouse.io/api/v1/labels/{label-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/labels/{label-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
label-public-id Integer Required. The ID of the label you wish to delete.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Linked-Files

List Linked Files

List Linked Files returns a list of all Linked-Files and their attributes.

Definition

GET https://api.clubhouse.io/api/v1/linked-files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/linked-files?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "thumbnail_url": "foo",
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "description": "foo",
    "size": 123,
    "created_at": "2016-12-31T12:30:00Z",
    "content_type": "foo",
    "story_ids": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo",
    "id": 123,
    "type": "foo"
  }
]

Responses

Code Description
200 [ LinkedFile, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Linked File

Create Linked File allows you to create a new Linked File in Clubhouse.

Definition

POST https://api.clubhouse.io/api/v1/linked-files

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "story_id": 123, "uploader_id": "12345678-9012-3456-7890-123456789012", "name": "foo", "thumbnail_url": "foo", "description": "foo", "size": 123, "content_type": "foo", "url": "foo", "type": "google" }' \
  -L "https://api.clubhouse.io/api/v1/linked-files?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "name": "foo",
  "thumbnail_url": "foo",
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "size": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "content_type": "foo",
  "story_ids": [123],
  "updated_at": "2016-12-31T12:30:00Z",
  "url": "foo",
  "id": 123,
  "type": "foo"
}

Body Parameters

Name Description
content_type String The content type of the image (e.g. txt/plain).
description String The description of the file.
name String Required. The name of the file.
size Integer The filesize, if the integration provided it.
story_id Integer The ID of the linked story.
thumbnail_url String The URL of the thumnail, if the integration provided it.
type Enum (google, url, dropbox, box, onedrive) Required. The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the user that uploaded the file.
url String Required. The URL of linked file.

Responses

Code Description
201 LinkedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Linked File

Get File returns information about the selected Linked File.

Definition

GET https://api.clubhouse.io/api/v1/linked-files/{linked-file-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/linked-files/{linked-file-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "name": "foo",
  "thumbnail_url": "foo",
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "size": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "content_type": "foo",
  "story_ids": [123],
  "updated_at": "2016-12-31T12:30:00Z",
  "url": "foo",
  "id": 123,
  "type": "foo"
}

URL Parameters

Name Description
linked-file-public-id Integer Required. The unique identifier of the linked file.

Responses

Code Description
200 LinkedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Linked File

Updated Linked File allows you to update properties of a previously attached Linked-File.

Definition

PUT https://api.clubhouse.io/api/v1/linked-files/{linked-file-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "uploader_id": "12345678-9012-3456-7890-123456789012", "url": "foo", "name": "foo", "thumbnail_url": "foo", "type": "google", "description": "foo", "size": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/linked-files/{linked-file-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "name": "foo",
  "thumbnail_url": "foo",
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "size": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "content_type": "foo",
  "story_ids": [123],
  "updated_at": "2016-12-31T12:30:00Z",
  "url": "foo",
  "id": 123,
  "type": "foo"
}

URL Parameters

Name Description
linked-file-public-id Integer Required. The unique identifier of the linked file.

Body Parameters

Name Description
description String The description of the file.
name String The name of the file.
size String The filesize, if the integration provided it.
thumbnail_url String The URL of the thumnail, if the integration provided it.
type Enum (google, url, dropbox, box, onedrive) The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the user that uploaded the file.
url String The URL of linked file.

Responses

Code Description
200 LinkedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Linked File

Delete Linked File can be used to delete any previously attached Linked-File.

Definition

DELETE https://api.clubhouse.io/api/v1/linked-files/{linked-file-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/linked-files/{linked-file-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
linked-file-public-id Integer Required. The unique identifier of the Linked File.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Projects

List Projects

List Projects returns a list of all Projects and their attributes.

Definition

GET https://api.clubhouse.io/api/v1/projects

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/projects?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "num_points": 123,
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "archived": true,
    "description": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "color": "foo",
    "num_stories": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "abbreviation": "foo",
    "id": 123
  }
]

Responses

Code Description
200 [ Project, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Project

Create Project is used to create a new Clubhouse Project.

Definition

POST https://api.clubhouse.io/api/v1/projects

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "description": "foo", "created_at": "2016-12-31T12:30:00Z", "color": "foo", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "abbreviation": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/projects?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "num_points": 123,
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "archived": true,
  "description": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "color": "foo",
  "num_stories": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "abbreviation": "foo",
  "id": 123
}

Body Parameters

Name Description
abbreviation String The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
color String The color you wish to use for the Project in the system.
created_at Date Defaults to the time it is created but can be set to reflect another date.
description String The Project description.
external_id String This field can be set to another unique ID. In the case that the Project has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any users you want to add as Owners on this new Epic.
name String Required. The name of the Project.
updated_at Date Defaults to the time it is created but can be set to reflect another date.

Responses

Code Description
201 Project
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Stories

List Stories returns a list of all Stories in a selected Project and their attributes.

Definition

GET https://api.clubhouse.io/api/v1/projects/{project-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/projects/{project-public-id}/stories?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "linked_file_ids": [123],
    "comments": [{
      "author_id": "12345678-9012-3456-7890-123456789012",
      "story_id": 123,
      "position": 123,
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "created_at": "2016-12-31T12:30:00Z",
      "text": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123
    }],
    "estimate": 123,
    "created_at": "2016-12-31T12:30:00Z",
    "story_type": "foo",
    "file_ids": [123],
    "id": 123,
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "subject_id": 123,
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo",
      "type": "foo",
      "object_id": 123,
      "id": 123
    }],
    "labels": [{
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "name": "foo",
      "id": 123
    }],
    "project_id": 123,
    "epic_id": 123,
    "tasks": [{
      "story_id": 123,
      "position": 123,
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "description": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123,
      "completed_at": "2016-12-31T12:30:00Z",
      "complete": true
    }],
    "deadline": "2016-12-31T12:30:00Z",
    "name": "foo",
    "description": "foo",
    "archived": true,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_state_id": 123
  }
]

URL Parameters

Name Description
project-public-id Integer Required. The unique ID of the Project.

Responses

Code Description
200 [ Story, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Project

Get Project returns information about the selected Project.

Definition

GET https://api.clubhouse.io/api/v1/projects/{project-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/projects/{project-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "num_points": 123,
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "archived": true,
  "description": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "color": "foo",
  "num_stories": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "abbreviation": "foo",
  "id": 123
}

URL Parameters

Name Description
project-public-id Integer Required. The unique ID of the Project.

Responses

Code Description
200 Project
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Project

Update Project can be used to change properties of a Project.

Definition

PUT https://api.clubhouse.io/api/v1/projects/{project-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "color": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "abbreviation": "foo", "archived": true, "description": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/projects/{project-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "num_points": 123,
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "archived": true,
  "description": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "color": "foo",
  "num_stories": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "abbreviation": "foo",
  "id": 123
}

URL Parameters

Name Description
project-public-id Integer Required. The ID of the Project.

Body Parameters

Name Description
abbreviation String The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
archived Boolean A true/false boolean indicating whether the Story is in archived state.
color String The color that represents the Project in the UI.
description String The Project’s description.
follower_ids Array [UUID] An array of UUIDs for any Users you want to add as Followers.
name String The Project’s name.

Responses

Code Description
200 Project
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Project

Delete Project can be used to delete a Project. Projects can only be deleted if all associated Stories are moved or deleted. In the case that the Project cannot be deleted, you will receive a 422 response.

Definition

DELETE https://api.clubhouse.io/api/v1/projects/{project-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/projects/{project-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
project-public-id Integer Required. The ID of the Project that you wish to delete.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Story-Links

Create Story Link

Story links allow you create semantic relationships between two stories. Relationship types are relates to, blocks / blocked by, and duplicates / is duplicated by. The format is subject -> link -> object, or for example “story 5 blocks story 6”.

Definition

POST https://api.clubhouse.io/api/v1/story-links

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "subject_id": 123, "verb": "blocks", "object_id": 123 }' \
  -L "https://api.clubhouse.io/api/v1/story-links?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "subject_id": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "verb": "foo",
  "object_id": 123,
  "id": 123
}

Body Parameters

Name Description
object_id Integer Required. The ID of the object story.
subject_id Integer Required. The ID of the subject story.
verb Enum (blocks, duplicates, relates to) Required. The type of link.

Responses

Code Description
201 StoryLink
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Story Link

Returns information about the selected Story Link.

Definition

GET https://api.clubhouse.io/api/v1/story-links/{story-link-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/story-links/{story-link-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "subject_id": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "verb": "foo",
  "object_id": 123,
  "id": 123
}

URL Parameters

Name Description
story-link-public-id Integer Required. The unique identifier of the Story Link.

Responses

Code Description
200 StoryLink
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Story Link

Delete Story-Link can be used to delete any Story Link.

Definition

DELETE https://api.clubhouse.io/api/v1/story-links/{story-link-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/story-links/{story-link-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
story-link-public-id Integer Required. The unique identifier of the Story Link.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Stories

Create Multiple Stories

Create Multiple Stories allows you to create multiple stories in a single request using the same syntax as Create_Story.

Definition

POST https://api.clubhouse.io/api/v1/stories/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "stories": [{ "follower_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "linked_file_ids": [123], "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "external_id": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "text": "foo"
  }], "estimate": 123, "created_at": "2016-12-31T12:30:00Z", "story_type": "feature", "file_ids": [123], "story_links": [{
    "subject_id": 123,
    "verb": "blocks",
    "object_id": 123
  }], "labels": [{
    "external_id": "foo",
    "name": "foo"
  }], "project_id": 123, "epic_id": 123, "tasks": [{
    "created_at": "2016-12-31T12:30:00Z",
    "external_id": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "description": "foo",
    "complete": true
  }], "deadline": "2016-12-31T12:30:00Z", "name": "foo", "description": "foo", "requested_by_id": "12345678-9012-3456-7890-123456789012", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }] }' \
  -L "https://api.clubhouse.io/api/v1/stories/bulk?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "linked_file_ids": [123],
    "comments": [{
      "author_id": "12345678-9012-3456-7890-123456789012",
      "story_id": 123,
      "position": 123,
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "created_at": "2016-12-31T12:30:00Z",
      "text": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123
    }],
    "estimate": 123,
    "created_at": "2016-12-31T12:30:00Z",
    "story_type": "foo",
    "file_ids": [123],
    "id": 123,
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "subject_id": 123,
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo",
      "type": "foo",
      "object_id": 123,
      "id": 123
    }],
    "labels": [{
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "name": "foo",
      "id": 123
    }],
    "project_id": 123,
    "epic_id": 123,
    "tasks": [{
      "story_id": 123,
      "position": 123,
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "description": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123,
      "completed_at": "2016-12-31T12:30:00Z",
      "complete": true
    }],
    "deadline": "2016-12-31T12:30:00Z",
    "name": "foo",
    "description": "foo",
    "archived": true,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_state_id": 123
  }
]

Body Parameters

Name Description
stories Array [CreateStoryParams] Required. An array of stories to be created.

Responses

Code Description
201 [ Story, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Multiple Stories

Update Multiple Stories allows you to make changes to numerous stories at once.

Definition

PUT https://api.clubhouse.io/api/v1/stories/bulk

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "deadline": "2016-12-31T12:30:00Z", "labels_add": [{ "external_id": "foo", "name": "foo" }], "archived": true, "labels_remove": [{ "external_id": "foo", "name": "foo" }], "estimate": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "story_ids": [123], "story_type": "feature", "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "workflow_state_id": 123, "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "epic_id": 123 }' \
  -L "https://api.clubhouse.io/api/v1/stories/bulk?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "linked_file_ids": [123],
    "comments": [{
      "author_id": "12345678-9012-3456-7890-123456789012",
      "story_id": 123,
      "position": 123,
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "created_at": "2016-12-31T12:30:00Z",
      "text": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123
    }],
    "estimate": 123,
    "created_at": "2016-12-31T12:30:00Z",
    "story_type": "foo",
    "file_ids": [123],
    "id": 123,
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "subject_id": 123,
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo",
      "type": "foo",
      "object_id": 123,
      "id": 123
    }],
    "labels": [{
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "name": "foo",
      "id": 123
    }],
    "project_id": 123,
    "epic_id": 123,
    "tasks": [{
      "story_id": 123,
      "position": 123,
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "description": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123,
      "completed_at": "2016-12-31T12:30:00Z",
      "complete": true
    }],
    "deadline": "2016-12-31T12:30:00Z",
    "name": "foo",
    "description": "foo",
    "archived": true,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_state_id": 123
  }
]

Body Parameters

Name Description
archived Boolean If the Stories should be archived or not.
deadline Date or null The due date of the Stories.
epic_id Integer or null The ID of the Epic the Stories should belong to.
estimate Integer or null The numeric point estimate of the Stories. Can also be null, which means unestimated.
follower_ids_add Array [UUID] The UUIDs of the new followers to be added.
follower_ids_remove Array [UUID] The UUIDs of the followers to be removed.
labels_add Array [CreateLabelParams] An array of labels to be added.
labels_remove Array [CreateLabelParams] An array of labels to be removed.
owner_ids_add Array [UUID] The UUIDs of the new owners to be added.
owner_ids_remove Array [UUID] The UUIDs of the owners to be removed.
project_id Integer The ID of the Project the Stories should belong to.
requested_by_id UUID The UUID of the story requester.
story_ids Array [Integer] Required. The unique IDs of the Stories you wish to update.
story_type Enum (feature, chore, bug) The type of story (feature, bug, chore).
workflow_state_id Integer The ID of the workflow state the Stories should be in.

Responses

Code Description
200 [ Story, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Story

Create Story is used to add a new story to your Clubhouse.

Definition

POST https://api.clubhouse.io/api/v1/stories

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "follower_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "linked_file_ids": [123], "comments": [{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "text": "foo" }], "estimate": 123, "created_at": "2016-12-31T12:30:00Z", "story_type": "feature", "file_ids": [123], "story_links": [{ "subject_id": 123, "verb": "blocks", "object_id": 123 }], "labels": [{ "external_id": "foo", "name": "foo" }], "project_id": 123, "epic_id": 123, "tasks": [{ "created_at": "2016-12-31T12:30:00Z", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "description": "foo", "complete": true }], "deadline": "2016-12-31T12:30:00Z", "name": "foo", "description": "foo", "requested_by_id": "12345678-9012-3456-7890-123456789012", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }' \
  -L "https://api.clubhouse.io/api/v1/stories?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "linked_file_ids": [123],
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "story_id": 123,
    "position": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "created_at": "2016-12-31T12:30:00Z",
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": 123
  }],
  "estimate": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "story_type": "foo",
  "file_ids": [123],
  "id": 123,
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "subject_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo",
    "type": "foo",
    "object_id": 123,
    "id": 123
  }],
  "labels": [{
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "id": 123
  }],
  "project_id": 123,
  "epic_id": 123,
  "tasks": [{
    "story_id": 123,
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "description": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": 123,
    "completed_at": "2016-12-31T12:30:00Z",
    "complete": true
  }],
  "deadline": "2016-12-31T12:30:00Z",
  "name": "foo",
  "description": "foo",
  "archived": true,
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_state_id": 123
}

Body Parameters

Name Description
comments Array [CreateCommentParams] An array to add Comments to the Story.
created_at Date Defaults to the time it is created but can be set to reflect another creation time/date.
deadline Date or null The Story’s deadline.
description String The Story’s description.
epic_id Integer or null The ID for the Project the Story is assigned to.
estimate Integer or null An integer used to express story point estimate for the Story.
external_id String This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
file_ids Array [Integer] The IDs of any Files you wish to attach to this Story.
follower_ids Array [UUID] An array of UUIDs for any Users you want to add as Followers on this new Story.
labels Array [CreateLabelParams] An array using to add Labels to the Story.
linked_file_ids Array [Integer] The IDs of any Linked Files you wish to attach to this Story.
name String Required. The Story name.
owner_ids Array [UUID] An array of UUIDs for any users you want to add as Owners on this new Story.
project_id Integer Required. The ID for the Project the Story is assigned to.
requested_by_id UUID Defaults to the token holder, but can be set to the UUID of any User.
story_links Array [CreateStoryLinkParams] An array to add Story Links.
story_type Enum (feature, chore, bug) Defaults to feature but can be “feature”, “chore”, or “bug”.
tasks Array [CreateTaskParams] An array used to add Tasks to the Story.
updated_at Date Defaults to the time the Story is created in Clubhouse but can be set to reflect another time/date.
workflow_state_id Integer The ID of the workflow state the Story is currently in.

Responses

Code Description
201 Story
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Task

Create Task is used to create a new task in a Story.

Definition

POST https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "created_at": "2016-12-31T12:30:00Z", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "description": "foo", "complete": true }' \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "story_id": 123,
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123,
  "completed_at": "2016-12-31T12:30:00Z",
  "complete": true
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Task will be in.

Body Parameters

Name Description
complete Boolean True/false boolean indicating whether the Task is completed. Defaults to false.
created_at Date Defaults to the time it is created but can be set to reflect another creation time/date.
description String Required. The Task description.
external_id String This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.
owner_ids Array [UUID] An array of UUIDs for any users you want to add as Owners on this new Task.
updated_at Date Defaults to the time the Task is created in Clubhouse but can be set to reflect another time/date.

Responses

Code Description
201 Task
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Story

Get Story returns information about a chosen Story.

Definition

GET https://api.clubhouse.io/api/v1/stories/{story-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "linked_file_ids": [123],
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "story_id": 123,
    "position": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "created_at": "2016-12-31T12:30:00Z",
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": 123
  }],
  "estimate": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "story_type": "foo",
  "file_ids": [123],
  "id": 123,
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "subject_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo",
    "type": "foo",
    "object_id": 123,
    "id": 123
  }],
  "labels": [{
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "id": 123
  }],
  "project_id": 123,
  "epic_id": 123,
  "tasks": [{
    "story_id": 123,
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "description": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": 123,
    "completed_at": "2016-12-31T12:30:00Z",
    "complete": true
  }],
  "deadline": "2016-12-31T12:30:00Z",
  "name": "foo",
  "description": "foo",
  "archived": true,
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_state_id": 123
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story.

Responses

Code Description
200 Story
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Story

Update Story can be used to update Story properties.

Definition

PUT https://api.clubhouse.io/api/v1/stories/{story-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "before_id": 123, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "linked_file_ids": [123], "estimate": 123, "after_id": 123, "story_type": "feature", "file_ids": [123], "labels": [{ "external_id": "foo", "name": "foo" }], "project_id": 123, "epic_id": 123, "deadline": "2016-12-31T12:30:00Z", "name": "foo", "description": "foo", "archived": true, "requested_by_id": "12345678-9012-3456-7890-123456789012", "workflow_state_id": 123 }' \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "linked_file_ids": [123],
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "story_id": 123,
    "position": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "created_at": "2016-12-31T12:30:00Z",
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": 123
  }],
  "estimate": 123,
  "created_at": "2016-12-31T12:30:00Z",
  "story_type": "foo",
  "file_ids": [123],
  "id": 123,
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "subject_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo",
    "type": "foo",
    "object_id": 123,
    "id": 123
  }],
  "labels": [{
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "id": 123
  }],
  "project_id": 123,
  "epic_id": 123,
  "tasks": [{
    "story_id": 123,
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "description": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": 123,
    "completed_at": "2016-12-31T12:30:00Z",
    "complete": true
  }],
  "deadline": "2016-12-31T12:30:00Z",
  "name": "foo",
  "description": "foo",
  "archived": true,
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_state_id": 123
}

URL Parameters

Name Description
story-public-id Integer Required. The unique identifier of this story.

Body Parameters

Name Description
after_id Integer The ID of the story we want to move this story after.
archived Boolean True if the story is archived, otherwise false.
before_id Integer The ID of the story we want to move this story before.
deadline Date or null The optional due date of the story.
description String The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
file_ids Array [Integer] An array of IDs of files attached to the story.
follower_ids Array [UUID] An array of UUIDs of the Followers on this story.
labels Array [CreateLabelParams] An array of labels attached to the story.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
name String The title of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer The ID of the project the story belongs to.
requested_by_id UUID The UUID of the story requester.
story_type Enum (feature, chore, bug) The type of story (feature, bug, chore).
workflow_state_id Integer The ID of the workflow state the Story should be in.

Responses

Code Description
200 Story
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Story

Delete Story can be used to delete any Story.

Definition

DELETE https://api.clubhouse.io/api/v1/stories/{story-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
story-public-id Integer Required. The Story’s unique ID.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Search Stories

Search Stories lets you search Stories based on desired parameters. While all parameters are optional, you must include at least one parameter in order to receive a response.

Definition

POST https://api.clubhouse.io/api/v1/stories/search

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "project_ids": [123], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "estimate": 123, "created_at_start": "2016-12-31T12:30:00Z", "story_type": "feature", "text": "foo", "epic_ids": [123], "workflow_state_types": [started], "updated_at_end": "2016-12-31T12:30:00Z", "updated_at_start": "2016-12-31T12:30:00Z", "project_id": 123, "epic_id": 123, "label_name": "foo", "archived": true, "requested_by_id": "12345678-9012-3456-7890-123456789012", "owner_id": "12345678-9012-3456-7890-123456789012", "workflow_state_id": 123, "created_at_end": "2016-12-31T12:30:00Z" }' \
  -L "https://api.clubhouse.io/api/v1/stories/search?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "linked_file_ids": [123],
    "comments": [{
      "author_id": "12345678-9012-3456-7890-123456789012",
      "story_id": 123,
      "position": 123,
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "created_at": "2016-12-31T12:30:00Z",
      "text": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123
    }],
    "estimate": 123,
    "created_at": "2016-12-31T12:30:00Z",
    "story_type": "foo",
    "file_ids": [123],
    "id": 123,
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "subject_id": 123,
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo",
      "type": "foo",
      "object_id": 123,
      "id": 123
    }],
    "labels": [{
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "name": "foo",
      "id": 123
    }],
    "project_id": 123,
    "epic_id": 123,
    "tasks": [{
      "story_id": 123,
      "position": 123,
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "description": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": 123,
      "completed_at": "2016-12-31T12:30:00Z",
      "complete": true
    }],
    "deadline": "2016-12-31T12:30:00Z",
    "name": "foo",
    "description": "foo",
    "archived": true,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_state_id": 123
  }
]

Body Parameters

Name Description
archived Boolean A true/false boolean indicating whether the Story is in archived state.
created_at_end Date Stories should have been created before this date.
created_at_start Date Stories should have been created after this date.
epic_id Integer or null The Epic ID that may be associated with the Stories.
epic_ids Array [Integer] The Epic IDs that may be associated with the Stories.
estimate Integer The number of estimate points associate with the Stories.
label_name String The name of any associated Labels.
owner_id UUID or null The UUID of the user the Stories should be owned by.
owner_ids Array [UUID] An array of UUIDs for any Users who may be Owners of the Stories.
project_id Integer The ID for the single Project the Stories can be assigned to.
project_ids Array [Integer] The IDs for the Projects the Stories may be assigned to.
requested_by_id UUID The UUID of any Users who may have requested the Stories.
story_type Enum (feature, chore, bug) The type of Stories that you want returned.
text String Full text search on Story names, comments, and descriptions.
updated_at_end Date Stories should have been updated before this date.
updated_at_start Date Stories should have been updated after this date.
workflow_state_id Integer The unique IDs of the specific Workflow States that the Stories should be in.
workflow_state_types Array [Enum (started, unstarted, done)] The type of Workflow State the Stories may be in.

Responses

Code Description
201 [ Story, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Comment

Get Comment is used to get Comment information.

Definition

GET https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments/{comment-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "author_id": "12345678-9012-3456-7890-123456789012",
  "story_id": 123,
  "position": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "created_at": "2016-12-31T12:30:00Z",
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that contains the Comment.
comment-public-id Integer Required. The unique ID of the Comment.

Responses

Code Description
200 Comment
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Comment

Update Comment replaces the text of the existing Comment.

Definition

PUT https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "text": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments/{comment-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "author_id": "12345678-9012-3456-7890-123456789012",
  "story_id": 123,
  "position": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "created_at": "2016-12-31T12:30:00Z",
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.
comment-public-id Integer Required. The ID of the Comment you wish to update.

Body Parameters

Name Description
text String Required. The new text for the Comment.

Responses

Code Description
200 Comment
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Comment

Delete a comment from any story.

Definition

DELETE https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments/{comment-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.
comment-public-id Integer Required. The ID of the Comment you wish to delete.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Comment

Create Comment allows you to create a Comment on any Story.

Definition

POST https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": "foo", "updated_at": "2016-12-31T12:30:00Z", "text": "foo" }' \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/comments?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "author_id": "12345678-9012-3456-7890-123456789012",
  "story_id": 123,
  "position": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "created_at": "2016-12-31T12:30:00Z",
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the associated Story

Body Parameters

Name Description
author_id UUID Defaults to the token holder.
created_at Date Defaults to the time it is created but can be set to reflect another date.
external_id String This field can be set to another unique ID. In the case that the Comment has been imported from another tool, the ID in the other tool can be indicated here.
text String Required. This is the text in the comment.
updated_at Date Defaults to the time it is created but can be set to reflect another date.

Responses

Code Description
201 Comment
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Task

Returns information about a chosen Task.

Definition

GET https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks/{task-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks/{task-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "story_id": 123,
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123,
  "completed_at": "2016-12-31T12:30:00Z",
  "complete": true
}

URL Parameters

Name Description
story-public-id Integer Required. The unique ID of the Story.
task-public-id Integer Required. The unique ID of the Task.

Responses

Code Description
200 Task
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Task

Update Task can be used to update Task properties.

Definition

PUT https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks/{task-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "after_id": 123, "before_id": 123, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "description": "foo", "complete": true }' \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks/{task-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "story_id": 123,
  "position": 123,
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "description": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "id": 123,
  "completed_at": "2016-12-31T12:30:00Z",
  "complete": true
}

URL Parameters

Name Description
story-public-id Integer Required. The unique identifier of the parent Story.
task-public-id Integer Required. The unique identifier of the Task you wish to update.

Body Parameters

Name Description
after_id Integer Move task after this task ID.
before_id Integer Move task before this task ID.
complete Boolean A true/false boolean indicating whether the task is complete.
description String The Task’s description.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.

Responses

Code Description
200 Task
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Task

Delete Task can be used to delete any previously created Task on a Story.

Definition

DELETE https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks/{task-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/stories/{story-public-id}/tasks/{task-public-id}?token=$CLUBHOUSE_API_TOKEN"

URL Parameters

Name Description
story-public-id Integer Required. The unique ID of the Story that the Task is associated with.
task-public-id Integer Required. The unique ID of the Task.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Users

List Users

List Users returns information about users in the organization.

Definition

GET https://api.clubhouse.io/api/v1/users

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/users?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "two_factor_auth_activated": true,
    "permissions": [{
      "initials": "foo",
      "email_address": "foo",
      "disabled": true,
      "gravatar_hash": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "id": "12345678-9012-3456-7890-123456789012",
      "role": "foo"
    }],
    "name": "foo",
    "deactivated": true,
    "id": "12345678-9012-3456-7890-123456789012",
    "username": "foo"
  }
]

Responses

Code Description
200 [ User, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get User

Returns information about a User.

Definition

GET https://api.clubhouse.io/api/v1/users/{user-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/users/{user-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "two_factor_auth_activated": true,
  "permissions": [{
    "initials": "foo",
    "email_address": "foo",
    "disabled": true,
    "gravatar_hash": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "id": "12345678-9012-3456-7890-123456789012",
    "role": "foo"
  }],
  "name": "foo",
  "deactivated": true,
  "id": "12345678-9012-3456-7890-123456789012",
  "username": "foo"
}

URL Parameters

Name Description
user-public-id UUID Required. The User’s unique ID.

Responses

Code Description
200 User
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Workflows

List Workflows

List Workflows returns a list containing the single Workflow in the organization and its attributes.

Definition

GET https://api.clubhouse.io/api/v1/workflows

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v1/workflows?token=$CLUBHOUSE_API_TOKEN"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "states": [{
      "position": 123,
      "name": "foo",
      "description": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "color": "foo",
      "num_stories": 123,
      "verb": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "type": "foo",
      "id": 123
    }],
    "default_state_id": 123,
    "id": 123
  }
]

Responses

Code Description
200 [ Workflow, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Resources

What follows are resource (or schema) definitions for everything referenced in the above endpoints.

Comment

A Comment is any note added within the Comment field of a Story.

Name Description
author_id UUID or null The unique ID of the User who is the Comment’s author.
created_at Date The time/date when the Comment was created.
id Integer The unique ID of the Comment.
mention_ids Array [UUID] The unique IDs of the User who are mentioned in the Comment.
position Integer The Comments numerical position in the list from oldest to newest.
story_id Integer The ID of the Story on which the Comment appears.
text String The text of the Comment.
updated_at Date or null The time/date when the Comment was updated.

CreateCommentParams

Request parameters for creating a Comment on a Clubhouse Story.

Name Description
author_id UUID The unique ID of the User who is the Comment’s author.
created_at Date The time/date when the Comment was created.
external_id String An optional user-defined ID perhaps associating Comment with an outside tool.
text String The text of the Comment.
updated_at Date The time/date when the Comment was updated.

CreateLabelParams

Request parameters for creating a Label on a Clubhouse story.

Name Description
external_id String An optional user-defined ID perhaps associating the Epic with an outside tool.
name String The Label name.

CreateStoryLinkParams

Request parameters for creating a Story Link within a Story.

Name Description
object_id Integer The unique ID of the Story defined as object.
subject_id Integer The unique ID of the Story defined as subject.
verb Enum (blocks, duplicates, relates to) How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”.

CreateStoryParams

Used to create multiple stories in a single request.

Name Description
comments Array [CreateCommentParams] An array of comments to add to the story.
created_at Date The datestamp of when the story was created.
deadline Date or null The due date of the story.
description String The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String An optional user-defined ID perhaps associating Task with an outside tool.
file_ids Array [Integer] An array of IDs of files attached to the story.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
labels Array [CreateLabelParams] An array of labels attached to the story.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
name String The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer The ID of the project the story belongs to.
requested_by_id UUID The ID of the user that requested the story.
story_links Array [CreateStoryLinkParams] An array of story links attached to the story.
story_type Enum (feature, chore, bug) The type of story (feature, bug, chore).
tasks Array [CreateTaskParams] An array of tasks connected to the story.
updated_at Date The datestamp of when the story last updated.
workflow_state_id Integer The ID of the workflow state the story is currently in.

CreateTaskParams

Request parameters for creating a Task on a Story.

Name Description
complete Boolean A true/false boolean indicating whether the Task is complete.
created_at Date The time/date that the Task was created.
description String The Task description.
external_id String An optional user-defined ID perhaps associating Task with an outside tool.
owner_ids Array [UUID] An array of unique IDs associated with the Users that own the Task.
updated_at Date The time/date that the Task was updated.

Epic

An Epic is a collection of stories that together might make up a release, a milestone, or some other large initiative that your organization is working on.

Name Description
archived Boolean True/false boolean that indicates whether the Epic is archived or not.
comments Array [ThreadedComment] A nested array of threaded comments.
created_at Date or null The time/date the Epic was created.
deadline Date or null The Epic’s deadline.
description String The Epic’s description.
follower_ids Array [UUID] An array of UUIDs for any Users you want to add as Followers on this Epic.
id Integer The unique ID of the Epic.
name String The name of the Epic.
owner_ids Array [UUID] An array of UUIDs for any users you want to add as Owners on this new Epic.
position Integer The Epic’s relative position in the Epic workflow state.
state String The workflow state that the Epic is in.
updated_at Date or null The time/date the Epic was updated.

File

A File is any document uploaded to your Clubhouse. Files attached from a third-party service can be accessed using the Linked Files endpoint.

Name Description
content_type String Free form string corresponding to a text or image file.
created_at Date The time/date that the file was created.
description String or null The description of the file.
filename String The name assigned to the file in Clubhouse upon upload.
id Integer The unique ID for the file.
mention_ids Array [UUID] The unique IDs of the Users who are mentioned in the file description.
name String The optional User-specified name of the file.
size Integer The size of the file.
story_ids Array [Integer] The unique IDs of the Stories associated with this file.
thumbnail_url String or null The url where the thumbnail of the file can be found in Clubhouse.
updated_at Date or null The time/date that the file was updated.
uploader_id UUID The unique ID of the User who uploaded the file.
url String or null The URL for the file.

Label

A Label can be used to associate Stories and also to filter Stories and create new Workspaces.

Name Description
created_at Date or null The time/date that the Label was created.
id Integer The unique ID of the Label.
name String The name of the Label.
updated_at Date or null The time/date that the Label was updated.

LabelWithCounts

Provides you with the number of Stories associated with this Label.

Name Description
created_at Date or null The time/date that the Label was created.
id Integer The unique ID of the Label.
name String The name of the Label.
num_stories_completed Integer The number of Stories with this Label that have been completed.
num_stories_in_progress Integer The number of Stories with this Label that are in progress.
num_stories_total Integer The number of Stories with this Label total.
updated_at Date or null The time/date that the Label was updated.

LinkedFile

Linked files are stored on a third-party website and linked to one or more Stories. Clubhouse currently supports linking files from Google Drive, Dropbox, Box, and by URL.

Name Description
content_type String or null The content type of the image (e.g. txt/plain).
created_at Date The datestamp of when the story was created.
description String or null The description of the file.
id Integer The unique identified of the file.
mention_ids Array [UUID] The users that are mentioned in the description of the file.
name String The name of the linked file.
size Integer or null The filesize, if the integration provided it.
story_ids Array [Integer] The IDs of the stories this file is attached to.
thumbnail_url String or null The URL of the file thumbnail, if the integration provided it.
type String The integration type (e.g. google, dropbox, box).
updated_at Date The datestamp of when the story was last updated.
uploader_id UUID The UUID of the user that uploaded the file.
url String The URL of the file.

Permission

Individual User permissions within the Clubhouse organization that has issued the token.

Name Description
created_at Date or null The time/date that the Permission was created.
disabled Boolean True/false boolean indicating whether the Permission has been disabled.
email_address String The primary email address of the User.
gravatar_hash String This is the gravatar hash associated with email_address.
id UUID The User’s ID in Clubhouse.
initials String The User’s initials in the system.
role String The User’s role in the Clubhouse organization.
updated_at Date or null The time/date that the Permission was last updated.

Project

Projects typically map to teams (such as Frontend, Backend, Mobile, Devops, etc) but can represent any open-ended product, component, or initiative.

Name Description
abbreviation String or null The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
archived Boolean True/false boolean indicating whether the Project is in an Archived state.
color String or null The color associated with the Project in the Clubhouse user interface.
created_at Date or null The time/date that the Project was created.
description String or null The description of the Project.
follower_ids Array [UUID] An array of UUIDs for any Users listed as Followers.
id Integer The unique ID of the Project.
name String The name of the Project
num_points Integer Number of Story points associated with this Project.
num_stories Integer The number of Stories assigned to this Project.
updated_at Date or null The time/date that the Project was last updated.

Story

Stories are the standard unit of work in Clubhouse and represent individual features, bugs, and chores.

Name Description
archived Boolean True if the story has been archived or not.
comments Array [Comment] An array of comments attached to the story.
created_at Date The datestamp of when the story was created.
deadline Date or null The due date of the story.
description String The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
file_ids Array [Integer] An array of IDs of files attached to the story.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
id Integer The unique identifier of the story.
labels Array [Label] An array of labels attached to the story.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
name String The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
position Integer A number representing the position of the story in relation to every other story in the current project.
project_id Integer The ID of the project the story belongs to.
requested_by_id UUID The ID of the user that requested the story.
story_links Array [TypedStoryLink] An array of story links attached to the story.
story_type String The type of story (feature, bug, chore).
tasks Array [Task] An array of tasks connected to the story.
updated_at Date or null The datestamp of when the story last updated.
workflow_state_id Integer The ID of the workflow state the story is currently in.

Story links allow you create semantic relationships between two stories. Relationship types are relates to, blocks / blocked by, and duplicates / is duplicated by. The format is subject -> link -> object, or for example “story 5 blocks story 6”.

Name Description
created_at Date The time/date when the Story link was created.
id Integer The unique identifier of the Story Link.
object_id Integer The ID of the object Story.
subject_id Integer The ID of the Subject story.
updated_at Date The time/date when the Story Link was last updated.
verb String The type of Story Link. This can be “blocks”, “duplicates”, or “relates to”.

Task

Name Description
complete Boolean True/false boolean indicating whether the Task has been completed.
completed_at Date or null The time/date the Task was completed.
created_at Date The time/date the Task was created.
description String Full text of the Task.
id Integer The unique ID of the Task.
mention_ids Array [UUID] An array of UUIDs of Users mentioned in this Task.
owner_ids Array [UUID] An array of UUIDs of the Owners of this Task.
position Integer The number corresponding to the Task’s position within a list of Tasks on a Story.
story_id Integer The unique identifier of the parent Story.
updated_at Date or null The time/date the Task was updated.

ThreadedComment

Comments associated with Epic Discussions.

Name Description
author_id UUID The unique ID of the User that authored the comment.
comments Array [ThreadedComment] A nested array of threaded comments.
created_at Date The time/date the comment was created.
deleted Boolean True/false boolean indicating whether the comment is deleted.
id Integer The unique ID of the comment.
text String The text of the comment.
updated_at Date The time/date the comment was updated.

The type of Story Link. The string can be subject or object.

Name Description
created_at Date The time/date when the Story link was created.
id Integer The unique identifier of the Story Link.
object_id Integer The ID of the object Story.
subject_id Integer The ID of the subject Story.
type String This indicates whether the Story is the subject or object in the Story Link.
updated_at Date The time/date when the Story link was updated.
verb String How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”.

User

Details about individual Clubhouse user as it relates to the Clubhouse organization that has issued the token.

Name Description
deactivated Boolean A true/false boolean indicating whether the User is deactivated in the system.
id UUID The unique ID associated with the User.
name String The User’s name in the system.
permissions Array [Permission] The User’s role in your Clubhouse organization.
two_factor_auth_activated Boolean If Two Factor Authentication is activated for this User.
username String The User’s username.

Workflow

Workflow is the array of defined Workflow States. Workflow can be queried using the API but must be updated in the Clubhouse UI.

Name Description
created_at Date The date the Workflow was created.
default_state_id Integer The unique ID of the default state that new Stories are entered into.
id Integer The unique ID of the Workflow.
states Array [WorkflowState] A map of the states in this Workflow.
updated_at Date The date the Workflow was updated.

WorkflowState

Workflow State is any of the at least 3 columns. Workflow States correspond to one of 3 types: Unstarted, Started, or Finished.

Name Description
color String The hex color for this Workflow State.
created_at Date The time/date the Workflow State was created.
description String The description of what sort of Stories belong in that Workflow state.
id Integer The unique ID of the Workflow State.
name String The Workflow State’s name.
num_stories Integer The number of Stories currently in that Workflow State.
position Integer The column that the State is in numbered from rom 1 - 23 from left to right.
type String The type of Workflow State (Unstarted, Started, or Finished)
updated_at Date When the Workflow State was last updated.
verb String or null The verb that triggers a move to that Workflow State when making GitHub commits.