NAV
API Documentation:
shell

Clubhouse API

Introduction

The Clubhouse REST 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 v2, the latest stable version of our REST API. If you’re building a library, we recommend using v2. 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.

Rate Limiting

The Clubhouse REST API limits requests to 200 per minute. Any requests over that limit will not be processed, and will return a 429 (“Too Many Requests”) response code.

Response Formats

We respond with JSON by default, however you can request data in CSV format by using a Accept: text/csv request header in addition to 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.

Migrating from v1 to v2

What follows is a list of endpoint and resource changes between the (now deprecated) v1 release and the current (stable) v2 release.

Endpoints Added

Endpoints Removed

Endpoint Changes

New Resources

Resources Removed

Change Log

2017/10/13

2017/09/28

2017/09/13

Categories

List Categories

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

Definition

GET https://api.clubhouse.io/api/v2/categories

Example Request

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

Example Response

[
  {
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

Responses

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

Create Category

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

Definition

POST https://api.clubhouse.io/api/v2/categories

Example Request

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

Example Response

{
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
color String The hex color to be displayed with the Label (for example, “#ff0000”).
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.
type Enum (milestone) Required. The type of entity this Category is associated with; currently Milestone is the only type of Category.

Responses

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

Get Category

Get Category returns information about the selected Category.

Definition

GET https://api.clubhouse.io/api/v2/categories/{category-public-id}

Example Request

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

Example Response

{
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
category-public-id Integer Required. The unique ID of the Category.

Responses

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

Update Category

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

Definition

PUT https://api.clubhouse.io/api/v2/categories/{category-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "archived": true, "color": "foo", "name": "foo" }' \
  -L "https://api.clubhouse.io/api/v2/categories/{category-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

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

Body Parameters

Name Description
archived Boolean A true/false boolean indicating if the Category has been archived.
color String or null The hex color to be displayed with the Category (for example, “#ff0000”).
name String The new name of the Category.

Responses

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

Delete Category

Delete Category can be used to delete any Category.

Definition

DELETE https://api.clubhouse.io/api/v2/categories/{category-public-id}

Example Request

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

URL Parameters

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

Responses

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

Epics

List Epics

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

Definition

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

Example Request

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

Example Response

[
  {
    "archived": true,
    "comments": [{
      "author_id": "12345678-9012-3456-7890-123456789012",
      "comments": [Recursive],
      "created_at": "2016-12-31T12:30:00Z",
      "deleted": true,
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "text": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "labels": [{
      "archived": true,
      "color": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "stats": {
        "num_epics": 123,
        "num_points_completed": 123,
        "num_points_in_progress": 123,
        "num_points_total": 123,
        "num_stories_completed": 123,
        "num_stories_in_progress": 123,
        "num_stories_total": 123,
        "num_stories_unestimated": 123
      },
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "milestone_id": 123,
    "name": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "project_ids": [123],
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "last_story_update": "2016-12-31T12:30:00Z",
      "num_points": 123,
      "num_points_done": 123,
      "num_points_started": 123,
      "num_points_unstarted": 123,
      "num_stories_done": 123,
      "num_stories_started": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

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/v2/epics

Example Request

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

Example Response

{
  "archived": true,
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [Recursive],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "labels": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "milestone_id": 123,
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "project_ids": [123],
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "last_story_update": "2016-12-31T12:30:00Z",
    "num_points": 123,
    "num_points_done": 123,
    "num_points_started": 123,
    "num_points_unstarted": 123,
    "num_stories_done": 123,
    "num_stories_started": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
completed_at_override Date A manual override for the time/date the Epic was completed.
created_at Date Defaults to the time/date 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 Members you want to add as Followers on this new Epic.
labels Array [CreateLabelParams] An array of Labels attached to the Epic.
milestone_id Integer or null The ID of the Milestone this Epic is related to.
name String Required. The Epic’s name.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
started_at_override Date A manual override for the time/date the Epic was started.
state Enum (done, in progress, to do) The Epic’s state (to do, in progress, or done).
updated_at Date Defaults to the time/date 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

Get Epic

Get Epic returns information about the selected Epic.

Definition

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

Example Request

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

Example Response

{
  "archived": true,
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [Recursive],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "labels": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "milestone_id": 123,
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "project_ids": [123],
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "last_story_update": "2016-12-31T12:30:00Z",
    "num_points": 123,
    "num_points_done": 123,
    "num_points_started": 123,
    "num_points_unstarted": 123,
    "num_stories_done": 123,
    "num_stories_started": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

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/v2/epics/{epic-public-id}

Example Request

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

Example Response

{
  "archived": true,
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [Recursive],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "labels": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "milestone_id": 123,
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "project_ids": [123],
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "last_story_update": "2016-12-31T12:30:00Z",
    "num_points": 123,
    "num_points_done": 123,
    "num_points_started": 123,
    "num_points_unstarted": 123,
    "num_stories_done": 123,
    "num_stories_started": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

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.
completed_at_override Date or null A manual override for the time/date the Epic was completed.
deadline Date or null The Epic’s deadline.
description String The Epic’s description.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers on this Epic.
labels Array [CreateLabelParams] An array of Labels attached to the Epic.
milestone_id Integer or null The ID of the Milestone this Epic is related to.
name String The Epic’s name.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this Epic.
started_at_override Date or null A manual override for the time/date the Epic was started.
state Enum (done, in progress, to do) 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/v2/epics/{epic-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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 Epic Comments

Get a list of all Comments on an Epic.

Definition

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

Example Request

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

Example Response

[
  {
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [{
      "author_id": "12345678-9012-3456-7890-123456789012",
      "comments": [Recursive],
      "created_at": "2016-12-31T12:30:00Z",
      "deleted": true,
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "text": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

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

Responses

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

Create Epic Comment

This endpoint allows you to create a threaded comment on an epic.

Definition

POST https://api.clubhouse.io/api/v2/epics/{epic-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", "text": "foo", "updated_at": "2016-12-31T12:30:00Z" }' \
  -L "https://api.clubhouse.io/api/v2/epics/{epic-public-id}/comments?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "author_id": "12345678-9012-3456-7890-123456789012",
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [Recursive],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

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

Body Parameters

Name Description
author_id UUID The Member ID of the Comment’s author.
created_at Date Defaults to the time/date the comment 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 Epic comment has been imported from another tool, the ID in the other tool can be indicated here.
text String Required. The comment text.
updated_at Date Defaults to the time/date the comment is last updated, but can be set to reflect another date.

Responses

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

Get Epic Comment

Get Epic Comment returns information about the selected Epic Comment.

Definition

GET https://api.clubhouse.io/api/v2/epics/{epic-public-id}/comments/{comment-public-id}

Example Request

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

Example Response

{
  "author_id": "12345678-9012-3456-7890-123456789012",
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [Recursive],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
epic-public-id Integer Required. The ID of the associated Epic.
comment-public-id Integer Required. The ID of the parent Epic comment.

Responses

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

Create Epic Comment Comment

This endpoint allows you to create a nested comment reply to an existing epic comment.

Definition

POST https://api.clubhouse.io/api/v2/epics/{epic-public-id}/comments/{comment-public-id}

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", "text": "foo", "updated_at": "2016-12-31T12:30:00Z" }' \
  -L "https://api.clubhouse.io/api/v2/epics/{epic-public-id}/comments/{comment-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "author_id": "12345678-9012-3456-7890-123456789012",
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [Recursive],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
epic-public-id Integer Required. The ID of the associated Epic.
comment-public-id Integer Required. The ID of the parent Epic comment.

Body Parameters

Name Description
author_id UUID
created_at Date
external_id String This field can be set to another unique ID. In the case that the Epic comment has been imported from another tool, the ID in the other tool can be indicated here.
text String Required. The comment text.
updated_at Date

Responses

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

Update Epic Comment

Definition

PUT https://api.clubhouse.io/api/v2/epics/{epic-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/v2/epics/{epic-public-id}/comments/{comment-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "author_id": "12345678-9012-3456-7890-123456789012",
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "comments": [Recursive],
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
epic-public-id Integer Required. The ID of the associated Epic.
comment-public-id Integer Required. The ID of the parent Epic comment.

Body Parameters

Name Description
text String Required. The updated comment text.

Responses

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

Delete Epic Comment

Definition

DELETE https://api.clubhouse.io/api/v2/epics/{epic-public-id}/comments/{comment-public-id}

Example Request

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

URL Parameters

Name Description
epic-public-id Integer Required. The ID of the associated Epic.
comment-public-id Integer Required. The ID of the parent Epic comment.

Responses

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

Files

List Files

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

Definition

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

Example Request

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

Example Response

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

Responses

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

Get File

Get File returns information about the selected File.

Definition

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

Example Request

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

Example Response

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

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/v2/files/{file-public-id}

Example Request

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

Example Response

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

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 Member 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/v2/files/{file-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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

Upload Files

Upload one or more Files, which can then be associated to a Story Description, Story Comment, or Epic Comment.

Definition

POST https://api.clubhouse.io/api/v2/files

Example Request

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/image1.jpg" \
  -F "file2=@/path/to/image2.jpg" \
  -L "https://api.clubhouse.io/api/v2/files?token=$CLUBHOUSE_API_TOKEN"

Example Response

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

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/v2/labels

Example Request

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

Example Response

[
  {
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

Responses

Code Description
200 [ Label, … ]
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/v2/labels

Example Request

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

Example Response

{
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stats": {
    "num_epics": 123,
    "num_points_completed": 123,
    "num_points_in_progress": 123,
    "num_points_total": 123,
    "num_stories_completed": 123,
    "num_stories_in_progress": 123,
    "num_stories_total": 123,
    "num_stories_unestimated": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
color String The hex color to be displayed with the Label (for example, “#ff0000”).
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 Label
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Label

Get Label returns information about the selected Label.

Definition

GET https://api.clubhouse.io/api/v2/labels/{label-public-id}

Example Request

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

Example Response

{
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stats": {
    "num_epics": 123,
    "num_points_completed": 123,
    "num_points_in_progress": 123,
    "num_points_total": 123,
    "num_stories_completed": 123,
    "num_stories_in_progress": 123,
    "num_stories_total": 123,
    "num_stories_unestimated": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
label-public-id Integer Required. The unique ID of the Label.

Responses

Code Description
200 Label
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/v2/labels/{label-public-id}

Example Request

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

Example Response

{
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stats": {
    "num_epics": 123,
    "num_points_completed": 123,
    "num_points_in_progress": 123,
    "num_points_total": 123,
    "num_stories_completed": 123,
    "num_stories_in_progress": 123,
    "num_stories_total": 123,
    "num_stories_unestimated": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

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

Body Parameters

Name Description
archived Boolean A true/false boolean indicating if the Label has been archived.
color String or null The hex color to be displayed with the Label (for example, “#ff0000”).
name String The new name of the label.

Responses

Code Description
200 Label
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/v2/labels/{label-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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/v2/linked-files

Example Request

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

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "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/v2/linked-files

Example Request

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

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "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 (box, dropbox, google, onedrive, url) Required. The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the member 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/v2/linked-files/{linked-file-public-id}

Example Request

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

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "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/v2/linked-files/{linked-file-public-id}

Example Request

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

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "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 (box, dropbox, google, onedrive, url) The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the member 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/v2/linked-files/{linked-file-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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

Members

List Members

List Members returns information about members of the organization.

Definition

GET https://api.clubhouse.io/api/v2/members

Example Request

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

Example Response

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

Responses

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

Get Member

Returns information about a Member.

Definition

GET https://api.clubhouse.io/api/v2/members/{member-public-id}

Example Request

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

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "disabled": true,
  "entity_type": "foo",
  "id": "12345678-9012-3456-7890-123456789012",
  "profile": {
    "deactivated": true,
    "display_icon": {
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": "12345678-9012-3456-7890-123456789012",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    },
    "email_address": "foo",
    "entity_type": "foo",
    "gravatar_hash": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "two_factor_auth_activated": true
  },
  "role": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
member-public-id UUID Required. The Member’s unique ID.

Responses

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

Milestones

List Milestones

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

Definition

GET https://api.clubhouse.io/api/v2/milestones

Example Request

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

Example Response

[
  {
    "categories": [{
      "archived": true,
      "color": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "name": "foo",
    "position": 123,
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

Responses

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

Create Milestone

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

Definition

POST https://api.clubhouse.io/api/v2/milestones

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "categories": [{ "color": "foo", "external_id": "foo", "name": "foo" }], "completed_at_override": "2016-12-31T12:30:00Z", "description": "foo", "name": "foo", "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
  -L "https://api.clubhouse.io/api/v2/milestones?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "categories": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Milestone.
completed_at_override Date A manual override for the time/date the Milestone was completed.
description String The Milestone’s description.
name String Required. The name of the Milestone.
started_at_override Date A manual override for the time/date the Milestone was started.
state Enum (done, in progress, to do) The workflow state that the Milestone is in.

Responses

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

Get Milestone

Get Milestone returns information about a chosen Milestone.

Definition

GET https://api.clubhouse.io/api/v2/milestones/{milestone-public-id}

Example Request

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

Example Response

{
  "categories": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
milestone-public-id Integer Required.

Responses

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

Update Milestone

Update Milestone can be used to update Milestone properties.

Definition

PUT https://api.clubhouse.io/api/v2/milestones/{milestone-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{ "after_id": 123, "before_id": 123, "categories": [{ "color": "foo", "external_id": "foo", "name": "foo" }], "completed_at_override": "2016-12-31T12:30:00Z", "description": "foo", "name": "foo", "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
  -L "https://api.clubhouse.io/api/v2/milestones/{milestone-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

{
  "categories": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
milestone-public-id Integer Required. The ID of the Milestone.

Body Parameters

Name Description
after_id Integer The ID of the Milestone we want to move this Milestone after.
before_id Integer The ID of the Milestone we want to move this Milestone before.
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Milestone.
completed_at_override Date or null A manual override for the time/date the Milestone was completed.
description String The Milestone’s description.
name String The name of the Milestone.
started_at_override Date or null A manual override for the time/date the Milestone was started.
state Enum (done, in progress, to do) The workflow state that the Milestone is in.

Responses

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

Delete Milestone

Delete Milestone can be used to delete any Milestone.

Definition

DELETE https://api.clubhouse.io/api/v2/milestones/{milestone-public-id}

Example Request

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

URL Parameters

Name Description
milestone-public-id Integer Required. The ID of the Milestone.

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/v2/projects

Example Request

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

Example Response

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

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/v2/projects

Example Request

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

Example Response

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

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/date 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 members you want to add as Owners on this new Epic.
iteration_length Integer The number of weeks per iteration in this Project.
name String Required. The name of the Project.
start_time Date
team_id Integer The ID of the team the project belongs to.
updated_at Date Defaults to the time/date 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

Get Project

Get Project returns information about the selected Project.

Definition

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

Example Request

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

Example Response

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

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/v2/projects/{project-public-id}

Example Request

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

Example Response

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

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.
days_to_thermometer Integer The number of days before the thermometer appears in the Story summary.
description String The Project’s description.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers.
name String The Project’s name.
show_thermometer Boolean Configuration to enable or disable thermometers in the Story summary.
team_id Integer The ID of the team the project belongs to.

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/v2/projects/{project-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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

List Stories

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

Definition

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

Example Request

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

Example Response

[
  {
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "labels": [{
      "archived": true,
      "color": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "stats": {
        "num_epics": 123,
        "num_points_completed": 123,
        "num_points_in_progress": 123,
        "num_points_total": 123,
        "num_stories_completed": 123,
        "num_stories_in_progress": 123,
        "num_stories_total": 123,
        "num_stories_unestimated": 123
      },
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "linked_file_ids": [123],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_type": "foo",
    "task_ids": [123],
    "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 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Repositories

List Repositories

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

Definition

GET https://api.clubhouse.io/api/v2/repositories

Example Request

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

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "full_name": "foo",
    "id": 123,
    "name": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }
]

Responses

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

Get Repository

Get Repository returns information about the selected Repository.

Definition

GET https://api.clubhouse.io/api/v2/repositories/{repo-public-id}

Example Request

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

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "full_name": "foo",
  "id": 123,
  "name": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "url": "foo"
}

URL Parameters

Name Description
repo-public-id Integer Required. The unique ID of the Repository.

Responses

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

Stories

Create Story

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

Definition

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

Example Request

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

Example Response

{
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": [{
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "name": "foo",
    "persistent": true,
    "pull_requests": [{
      "branch_id": 123,
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "target_branch_id": 123,
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    }],
    "repository_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "commits": [{
    "author_email": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "author_identity": {
      "entity_type": "foo",
      "name": "foo",
      "type": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "hash": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "message": "foo",
    "repository_id": 123,
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "epic_id": 123,
  "estimate": 123,
  "external_id": "foo",
  "files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "labels": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "linked_files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "project_id": 123,
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": 123,
    "object_id": 123,
    "subject_id": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo"
  }],
  "story_type": "foo",
  "tasks": [{
    "complete": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "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.
completed_at_override Date A manual override for the time/date the Story was completed.
created_at Date Defaults to the time/date 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 Members 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 members 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 Member.
started_at_override Date A manual override for the time/date the Story was started.
story_links Array [CreateStoryLinkParams] An array to add Story Links.
story_type Enum (bug, chore, feature) 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/date 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 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/v2/stories/bulk

Example Request

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

Example Response

[
  {
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "labels": [{
      "archived": true,
      "color": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "stats": {
        "num_epics": 123,
        "num_points_completed": 123,
        "num_points_in_progress": 123,
        "num_points_total": 123,
        "num_stories_completed": 123,
        "num_stories_in_progress": 123,
        "num_stories_total": 123,
        "num_stories_unestimated": 123
      },
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "linked_file_ids": [123],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_type": "foo",
    "task_ids": [123],
    "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 [ StorySlim, … ]
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/v2/stories/bulk

Example Request

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

Example Response

[
  {
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "labels": [{
      "archived": true,
      "color": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "stats": {
        "num_epics": 123,
        "num_points_completed": 123,
        "num_points_in_progress": 123,
        "num_points_total": 123,
        "num_stories_completed": 123,
        "num_stories_in_progress": 123,
        "num_stories_total": 123,
        "num_stories_unestimated": 123
      },
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "linked_file_ids": [123],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_type": "foo",
    "task_ids": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_state_id": 123
  }
]

Body Parameters

Name Description
after_id Integer The ID of the story that the stories are to be moved below.
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 (bug, chore, feature) 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 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Multiple Stories

Delete Multiple Stories allows you to delete multiple archived stories at once.

Definition

DELETE https://api.clubhouse.io/api/v2/stories/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -d '{ "story_ids": [123] }' \
  -L "https://api.clubhouse.io/api/v2/stories/bulk?token=$CLUBHOUSE_API_TOKEN"

Body Parameters

Name Description
story_ids Array [Integer] Required. The IDs of the archived stories to delete.

Responses

Code Description
204 No Content
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/v2/stories/{story-public-id}

Example Request

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

Example Response

{
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": [{
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "name": "foo",
    "persistent": true,
    "pull_requests": [{
      "branch_id": 123,
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "target_branch_id": 123,
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    }],
    "repository_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "commits": [{
    "author_email": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "author_identity": {
      "entity_type": "foo",
      "name": "foo",
      "type": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "hash": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "message": "foo",
    "repository_id": 123,
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "epic_id": 123,
  "estimate": 123,
  "external_id": "foo",
  "files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "labels": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "linked_files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "project_id": 123,
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": 123,
    "object_id": 123,
    "subject_id": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo"
  }],
  "story_type": "foo",
  "tasks": [{
    "complete": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "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/v2/stories/{story-public-id}

Example Request

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

Example Response

{
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": [{
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "name": "foo",
    "persistent": true,
    "pull_requests": [{
      "branch_id": 123,
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "target_branch_id": 123,
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    }],
    "repository_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "commits": [{
    "author_email": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "author_identity": {
      "entity_type": "foo",
      "name": "foo",
      "type": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "hash": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "message": "foo",
    "repository_id": 123,
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "epic_id": 123,
  "estimate": 123,
  "external_id": "foo",
  "files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "labels": [{
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "linked_files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "project_id": 123,
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": 123,
    "object_id": 123,
    "subject_id": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo"
  }],
  "story_type": "foo",
  "tasks": [{
    "complete": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "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.
branch_ids Array [Integer] An array of IDs of Branches attached to the story.
commit_ids Array [Integer] An array of IDs of Commits attached to the story.
completed_at_override Date or null A manual override for the time/date the Story was completed.
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.
started_at_override Date or null A manual override for the time/date the Story was started.
story_type Enum (bug, chore, feature) 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/v2/stories/{story-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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

Create Comment

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

Definition

POST https://api.clubhouse.io/api/v2/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", "text": "foo", "updated_at": "2016-12-31T12:30:00Z" }' \
  -L "https://api.clubhouse.io/api/v2/stories/{story-public-id}/comments?token=$CLUBHOUSE_API_TOKEN"

Example Response

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

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/date 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/date 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 Comment

Get Comment is used to get Comment information.

Definition

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

Example Request

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

Example Response

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

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/v2/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/v2/stories/{story-public-id}/comments/{comment-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

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

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/v2/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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 Task

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

Definition

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

Example Request

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

Example Response

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

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/date 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 members you want to add as Owners on this new Task.
updated_at Date Defaults to the time/date 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 Task

Returns information about a chosen Task.

Definition

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

Example Request

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

Example Response

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

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/v2/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, "complete": true, "description": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.clubhouse.io/api/v2/stories/{story-public-id}/tasks/{task-public-id}?token=$CLUBHOUSE_API_TOKEN"

Example Response

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

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/v2/stories/{story-public-id}/tasks/{task-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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

Story-Links

Create Story Link

Story links (called Story Relationships in the UI) allow you create semantic relationships between two stories. The parameters read like an active voice grammatical sentence: subject -> verb -> object.

The subject story acts on the object Story; the object story is the direct object of the sentence.

The subject story “blocks”, “duplicates”, or “relates to” the object story. Examples:

Definition

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

Example Request

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

Example Response

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

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/v2/story-links/{story-link-public-id}

Example Request

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

Example Response

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

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/v2/story-links/{story-link-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -L "https://api.clubhouse.io/api/v2/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

Teams

List Teams

List Teams returns a list of all Teams in the organization.

Definition

GET https://api.clubhouse.io/api/v2/teams

Example Request

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

Example Response

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

Responses

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

Get Team

Get Team is used to get Team information.

Definition

GET https://api.clubhouse.io/api/v2/teams/{team-public-id}

Example Request

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

Example Response

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

URL Parameters

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

Responses

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

Workflows

List Workflows

List Workflows returns a list of all Workflows in the organization.

Definition

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

Example Request

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

Example Response

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

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.

Branch

Branch refers to a GitHub branch. Branches are feature branches associated with Clubhouse Stories.

Name Description
created_at Date or null The time/date the Branch was created.
deleted Boolean A true/false boolean indicating if the Branch has been deleted.
entity_type String A string description of this resource.
id Integer or null The unique identifier of the Branch.
merged_branch_ids Array [Integer] The IDs of the Branches the Branch has been merged into.
name String The name of the Branch.
persistent Boolean A true/false boolean indicating if the Branch is persistent; e.g. master.
pull_requests Array [PullRequest] An array of PullRequests attached to the Branch (there is usually only one).
repository_id Integer or null The ID of the Repository that contains the Branch.
updated_at Date or null The time/date the Branch was updated.
url String The URL of the Branch.

Category

A Category can be used to associate Milestones.

Name Description
archived Boolean A true/false boolean indicating if the Category has been archived.
color String or null The hex color to be displayed with the Category (for example, “#ff0000”).
created_at Date The time/date that the Category was created.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.
id Integer The unique ID of the Category.
name String The name of the Category.
type String The type of entity this Category is associated with; currently Milestone is the only type of Category.
updated_at Date The time/date that the Category was updated.

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 Member who is the Comment’s author.
created_at Date The time/date when the Comment was created.
entity_type String A string description of this resource.
external_id String or null 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.
id Integer The unique ID of the Comment.
mention_ids Array [UUID] The unique IDs of the Member 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.

Commit

Commit refers to a GitHub commit and all associated details.

Name Description
author_email String The email address of the GitHub user that authored the Commit.
author_id UUID or null The ID of the Member that authored the Commit, if known.
author_identity Identity The Identity of the GitHub user that authored the Commit.
created_at Date The time/date the Commit was created.
entity_type String A string description of this resource.
hash String The Commit hash.
id Integer or null The unique identifier of the Commit.
merged_branch_ids Array [Integer] The IDs of the Branches the Commit has been merged into.
message String The Commit message.
repository_id Integer or null The ID of the Repository that contains the Commit.
timestamp Date The time/date the Commit was pushed.
updated_at Date or null The time/date the Commit was updated.
url String The URL of the Commit.

CreateCategoryParams

Request parameters for creating a Category with a Milestone.

Name Description
color String The hex color to be displayed with the Category (for example, “#ff0000”).
external_id String This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.
name String The name of the Category.

CreateCommentParams

Request parameters for creating a Comment on a Clubhouse Story.

Name Description
author_id UUID The unique ID of the Member 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
color String The hex color to be displayed with the Label (for example, “#ff0000”).
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.
completed_at_override Date A manual override for the time/date the Story was completed.
created_at Date The time/date 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 member that requested the story.
started_at_override Date A manual override for the time/date the Story was started.
story_links Array [CreateStoryLinkParams] An array of story links attached to the story.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
tasks Array [CreateTaskParams] An array of tasks connected to the story.
updated_at Date The time/date the Story was 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 Members 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.
completed Boolean A true/false boolean indicating if the Epic has been completed.
completed_at Date or null The time/date the Epic was completed.
completed_at_override Date or null A manual override for the time/date the Epic was completed.
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.
entity_type String A string description of this resource.
external_id String or null 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 Members you want to add as Followers on this Epic.
id Integer The unique ID of the Epic.
labels Array [Label] An array of Labels attached to the Epic.
milestone_id Integer or null The ID of the Milestone this Epic is related to.
name String The name of the Epic.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
position Integer The Epic’s relative position in the Epic workflow state.
project_ids Array [Integer] The IDs of Projects related to this Epic.
started Boolean A true/false boolean indicating if the Epic has been started.
started_at Date or null The time/date the Epic was started.
started_at_override Date or null A manual override for the time/date the Epic was started.
state String The workflow state that the Epic is in.
stats EpicStats A group of calculated values for this Epic.
updated_at Date or null The time/date the Epic was updated.

EpicStats

A group of calculated values for an Epic.

Name Description
last_story_update Date or null The date of the last update of a Story in this Epic.
num_points Integer The total number of points in this Epic.
num_points_done Integer The total number of completed points in this Epic.
num_points_started Integer The total number of started points in this Epic.
num_points_unstarted Integer The total number of unstarted points in this Epic.
num_stories_done Integer The total number of done Stories in this Epic.
num_stories_started Integer The total number of started Stories in this Epic.
num_stories_unestimated Integer The total number of Stories with no point estimate.
num_stories_unstarted Integer The total number of unstarted Stories in this Epic.

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.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the File has been imported from another tool, the ID in the other tool can be indicated here.
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 Members 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 Member who uploaded the file.
url String or null The URL for the file.

Icon

Icons are used to attach images to Organizations, Members, and Loading screens in the Clubhouse web application.

Name Description
created_at Date The time/date that the Icon was created.
entity_type String A string description of this resource.
id UUID The unique ID of the Icon.
updated_at Date The time/date that the Icon was updated.
url String The URL of the Icon.

Identity

Identity is your GitHub login. Clubhouse uses Identity to attempt to connect your GitHub actions with your Clubhouse Stories.

Name Description
entity_type String A string description of this resource.
name String or null This is your login in GitHub.
type String or null The type of Identity; currently only type is github.

Label

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

Name Description
archived Boolean A true/false boolean indicating if the Label has been archived.
color String or null The hex color to be displayed with the Label (for example, “#ff0000”).
created_at Date or null The time/date that the Label was created.
entity_type String A string description of this resource.
external_id String or null 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.
id Integer The unique ID of the Label.
name String The name of the Label.
stats LabelStats A group of calculated values for this Label.
updated_at Date or null The time/date that the Label was updated.

LabelStats

A group of calculated values for a Label.

Name Description
num_epics Integer The total number of Epics with this Label.
num_points_completed Integer The total number of completed points with this Label.
num_points_in_progress Integer The total number of in-progress points with this Label.
num_points_total Integer The total number of points with this Label.
num_stories_completed Integer The total number of completed Stories with this Label.
num_stories_in_progress Integer The total number of in-progress Stories with this Label.
num_stories_total Integer The total number of Stories with this Label.
num_stories_unestimated Integer The total number of Stories with no point estimate with this Label.

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 time/date the LinkedFile was created.
description String or null The description of the file.
entity_type String A string description of this resource.
id Integer The unique identified of the file.
mention_ids Array [UUID] The members 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 time/date the LinkedFile was updated.
uploader_id UUID The UUID of the member that uploaded the file.
url String The URL of the file.

Member

Details about individual Clubhouse user within the Clubhouse organization that has issued the token.

Name Description
created_at Date or null The time/date the Member was created.
disabled Boolean True/false boolean indicating whether the Member has been disabled within this Organization.
entity_type String A string description of this resource.
id UUID The Member’s ID in Clubhouse.
profile Profile A group of Member profile details.
role String The Member’s role in the Clubhouse organization.
updated_at Date or null The time/date the Member was last updated.

Milestone

A Milestone is a collection of Epics that represent a release or some other large initiative that your organization is working on.

Name Description
categories Array [Category] An array of Categories attached to the Milestone.
completed Boolean A true/false boolean indicating if the Milestone has been completed.
completed_at Date or null The time/date the Milestone was completed.
completed_at_override Date or null A manual override for the time/date the Milestone was completed.
created_at Date The time/date the Milestone was created.
description String The Milestone’s description.
entity_type String A string description of this resource.
id Integer The unique ID of the Milestone.
name String The name of the Milestone.
position Integer A number representing the position of the Milestone in relation to every other Milestone within the Organization.
started Boolean A true/false boolean indicating if the Milestone has been started.
started_at Date or null The time/date the Milestone was started.
started_at_override Date or null A manual override for the time/date the Milestone was started.
state String The workflow state that the Milestone is in.
updated_at Date The time/date the Milestone was updated.

Profile

Details about individual Clubhouse user’s profile within the Clubhouse organization that has issued the token.

Name Description
deactivated Boolean A true/false boolean indicating whether the Member has been deactivated within Clubhouse.
display_icon Icon or null The Member’s avatar Icon.
email_address String or null The primary email address of the Member with the Organization.
entity_type String A string description of this resource.
gravatar_hash String or null This is the gravatar hash associated with email_address.
id UUID The unique identifier of the profile.
mention_name String The Member’s username within the Organization.
name String The Member’s name within the Organization.
two_factor_auth_activated Boolean If Two Factor Authentication is activated for this User.

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 member interface.
created_at Date or null The time/date that the Project was created.
days_to_thermometer Integer The number of days before the thermometer appears in the Story summary.
description String or null The description of the Project.
entity_type String A string description of this resource.
external_id String or null 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 Members listed as Followers.
id Integer The unique ID of the Project.
iteration_length Integer The number of weeks per iteration in this Project.
name String The name of the Project
show_thermometer Boolean Configuration to enable or disable thermometers in the Story summary.
start_time Date The date at which the Project was started.
stats ProjectStats A group of calculated values for this Project.
team_id Integer The ID of the team the project belongs to.
updated_at Date or null The time/date that the Project was last updated.

ProjectStats

A group of calculated values for an Project.

Name Description
num_points Integer The total number of points in this Project.
num_stories Integer The total number of points in this Project.

PullRequest

Corresponds to a GitHub Pull Request attached to a Clubhouse story.

Name Description
branch_id Integer The ID of the branch for the particular pull request.
closed Boolean True/False boolean indicating whether the GitHub pull request has been closed.
created_at Date The time/date the pull request was created.
entity_type String A string description of this resource.
id Integer The unique ID associated with the pull request in Clubhouse.
num_added Integer Number of lines added in the pull request, according to GitHub.
num_commits Integer The number of commits on the pull request.
num_modified Integer Number of lines modified in the pull request, according to GitHub.
num_removed Integer Number of lines removed in the pull request, according to GitHub.
number Integer The pull requests unique number ID in GitHub.
target_branch_id Integer The ID of the target branch for the particular pull request.
title String The title of the pull request.
updated_at Date The time/date the pull request was created.
url String The URL for the pull request.

Repository

Repository refers to a GitHub repository.

Name Description
created_at Date or null The time/date the Repository was created.
entity_type String A string description of this resource.
external_id String or null The GitHub unique identifier for the Repository.
full_name String or null The full name of the GitHub repository.
id Integer or null The ID associated to the GitHub repository in Clubhouse.
name String or null The shorthand name of the GitHub repository.
type String The type of Repository. Currently this can only be “github”.
updated_at Date or null The time/date the Repository was updated.
url String or null The URL of the Repository.

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.
blocked Boolean A true/false boolean indicating if the Story is currently blocked.
blocker Boolean A true/false boolean indicating if the Story is currently a blocker of another story.
branches Array [Branch] An array of Git branches attached to the story.
comments Array [Comment] An array of comments attached to the story.
commits Array [Commit] An array of commits attached to the story.
completed Boolean A true/false boolean indicating if the Story has been completed.
completed_at Date or null The time/date the Story was completed.
completed_at_override Date or null A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
deadline Date or null The due date of the story.
description String The description of the story.
entity_type String A string description of this resource.
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 or null 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.
files Array [File] An array 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_files Array [LinkedFile] An array of linked files attached to the story.
moved_at Date or null
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 Member that requested the story.
started Boolean A true/false boolean indicating if the Story has been started.
started_at Date or null The time/date the Story was started.
started_at_override Date or null A manual override for the time/date the Story was started.
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 time/date the Story was 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.
entity_type String A string description of this resource.
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”.

StorySlim

StorySlim is a pared down version of the Story resource.

Name Description
archived Boolean True if the story has been archived or not.
blocked Boolean A true/false boolean indicating if the Story is currently blocked.
blocker Boolean A true/false boolean indicating if the Story is currently a blocker of another story.
comment_ids Array [Integer] An array of IDs of Comments attached to the story.
completed Boolean A true/false boolean indicating if the Story has been completed.
completed_at Date or null The time/date the Story was completed.
completed_at_override Date or null A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
deadline Date or null The due date of the story.
entity_type String A string description of this resource.
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 or null 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] An array of IDs of Files attached to the story.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
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 LinkedFiles attached to the story.
moved_at Date or null
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 Member that requested the story.
started Boolean A true/false boolean indicating if the Story has been started.
started_at Date or null The time/date the Story was started.
started_at_override Date or null A manual override for the time/date the Story was started.
story_links Array [TypedStoryLink] An array of story links attached to the story.
story_type String The type of story (feature, bug, chore).
task_ids Array [Integer] An array of IDs of Tasks attached to the story.
updated_at Date or null The time/date the Story was updated.
workflow_state_id Integer The ID of the workflow state the story is currently in.

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.
entity_type String A string description of this resource.
external_id String or null 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.
id Integer The unique ID of the Task.
mention_ids Array [UUID] An array of UUIDs of Members 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.

Team

Group of Projects with the same Workflow.

Name Description
created_at Date The time/date the Team was created.
description String The description of the Team.
entity_type String A string description of this resource.
id Integer The unique identifier of the Team.
name String The name of the Team.
position Integer A number representing the position of the Team in relation to every other Team within the Organization.
project_ids Array [Integer] An array of IDs of projects within the Team.
updated_at Date The time/date the Team was last updated.
workflow Workflow Details of the workflow associated with the Team.

ThreadedComment

Comments associated with Epic Discussions.

Name Description
author_id UUID The unique ID of the Member 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.
entity_type String A string description of this resource.
external_id String or null 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.
id Integer The unique ID of the Comment.
mention_ids Array [UUID] An array of Member IDs that have been mentioned in this 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.
entity_type String A string description of this resource.
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”.

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.
description String A description of the workflow.
entity_type String A string description of this resource.
id Integer The unique ID of the Workflow.
name String The name of the workflow.
states Array [WorkflowState] A map of the states in this Workflow.
team_id Integer The ID of the team the workflow belongs to.
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.
entity_type String A string description of this resource.
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 position that the Workflow State is in, starting with 0 at the left.
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.