Documentation (2024.2 Enterprise)

# Milestone

Milestone is a collection of Tasks in a Project.

- Attributes
- Child objects
- Operations
  - `GET /projects/:project_id/milestones`
  - `GET /projects/:project_id/milestones/:id`
  - `POST /projects/:project_id/milestones`
  - `PUT /projects/:project_id/milestones/:id`
  - `DELETE /projects/:project_id/milestones/:id`

## Attributes

Milestone object has support for storing custom attributes.

### id

URL-friendly identifier for the milestone.

- Type: `string`
- Immutable: `true`
- Unique: `true`
- Required: `true`
- Minimum length: `2`
- Maximum length: `100`
- Allowed characters: `a-z`, `A-Z`, `0-9`, `-`, `_`

### title

Human-readable title for the milestone.

- Type: `string`
- Required: `true`
- Minimum length: `1`
- Maximum length: `100`

### description

A free-form description of the milestone.

- Type: `string`
- Default: `""`
- Maximum length: `50000`

### default

An indicator of whether the milestone is a default one or not. Only one milestone can be set as a default within the project scope at the same time (setting this flag to `true` for one milestone unsets the same for the other ones).

- Type: `boolean`
- Default: `false`

### states

Possible states for the tasks in the milestone. A milestone must define at least one state.

- Type: `array`
- Required: `true`

### done_states

States that are considered as final task states in the milestone. Can be used to calculate progress of the milestone.

- Type: `array`

### priorities

Possible priorities for the tasks in the milestone. Priorities are considered to be integer based when left as empty.

- Type: `array`

### start_date

Optional start date of the milestone.

- Type: `timestamp`

### end_date

Optional end date of the milestone.

- Type: `timestamp`

## Child objects

The following child objects can be attached to the milestones returned, to eliminate the need for requesting them separately:

Object | Attribute
--- | ---
Task | `tasks`
User | `members`

For example to get all the tasks in the milestone, attach `include=tasks` to your GET request.

See the child object API documentation for a description of the possible operations.

## Operations

### GET /projects/:project_id/milestones

Returns all the milestones in the project, with optional limit and offset parameters, as a metadata-results object.

### GET /projects/:project_id/milestones/:id

Returns specific milestone object.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/milestones/default

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-05-12T12:41:39Z",
      "id": "default",
      "created_at": "2014-05-12T11:43:15Z",
      "updated_at": "2014-05-12T11:43:15Z",
      "title": "Default",
      "description": "The default milestone.",
      "default": false,
      "states": [
        "open",
        "wip",
        "blocked",
        "closed"
      ],
      "done_states": [
        "closed"
      ],
      "priorities": [
        "low",
        "normal",
        "high"
      ],
      "start_date": "2014-05-10T09:00:00Z",
      "end_date": null,
      "properties": {

      }
    }

### POST /projects/:project_id/milestones

Creates a new milestone to the project. Returns the created milestone object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "id": "default", "title": "Default milestone", "states": ["open"] }' \
      https://helixteamhub.cloud/api/projects/luotsi/milestones

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2014-05-12T15:02:10Z",
      "id": "default",
      "created_at": "2014-05-12T15:02:10Z",
      "updated_at": "2014-05-12T15:02:10Z",
      "title": "Default milestone",
      "description": "",
      "default": false,
      "states": [
        "open"
      ],
      "done_states": [

      ],
      "priorities": [

      ],
      "start_date": null,
      "end_date": null,
      "properties": {

      }
    }

### PUT /projects/:project_id/milestones/:id

Updates a milestone. Returns the updated milestone object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "description": "Sample description" }' \
      https://helixteamhub.cloud/api/projects/luotsi/milestones/default

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-05-12T15:03:58Z",
      "id": "default",
      "created_at": "2014-05-12T15:02:10Z",
      "updated_at": "2014-05-12T15:03:58Z",
      "title": "Default milestone",
      "description": "Sample description",
      "default": false,
      "states": [
        "open"
      ],
      "done_states": [

      ],
      "priorities": [

      ],
      "start_date": null,
      "end_date": null,
      "properties": {

      }
    }

### DELETE /projects/:project_id/milestones/:id

Deletes a milestone. Returns the deleted milestone object.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/milestones/default

Your search for returned results

Your search for returned results