Documentation (2024.2 Enterprise)

# Project

A project is where most of the collaboration happens in Helix TeamHub. A company can have 0 to n projects, and each project belongs to exactly one company. Most of the other objects are handled in the scope of projects.

- Attributes
- Searchable attributes
- Child objects
- Operations
  - `GET /projects`
  - `GET /projects/:id`
  - `POST /projects`
  - `PUT /projects/:id`
  - `DELETE /projects/:id`

## Attributes

Project object has support for storing custom attributes.

### id

A URL-friendly identifier for the project.

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

### name

The project's human-readable name.

- Type: `string`
- Unique: `true`
- Required: `true`
- Minimum length: `2`
- Maximum length: `100`

### visibility

The project's visibility flag: Can be visible to only its members or to all people in the company.

- Type: `string`
- Default: `company`
- Allowed values: `company`, `members`

### color

The background color of the default project avatar.

- Type: `string`
- Default: `blue`
- Allowed values: `blue`, `green`, `red`, `orange`, `turquoise`, `purple`

### labels

Possible labels for the tasks in the project.

- Type: `array`

### description

A free-form description of the project.

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

### hook_events

All hook events the project supports.

- Type: `array`

The hook_events array contains string identifiers of all the supported hook events.

    "hook_events": ["repository"]

### automatic_depot_creation

If set to true, a new Graph depot named //<project_short_name>/ is created in the Git Connector server. Any Git repositories added to the project will be automatically created in this depot

- Type: boolean
- Default: false

### properties

See custom attributes for more information.

## Searchable attributes

Projects can be searched by their `id`, `name`, and `description` attributes. See the search documentation for instructions how to do this.

## Child objects

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

Object | Attribute
--- | ---
User | `users`
Collaborator | `collaborators`
Groups | `groups`
Repository | `repositories`
Hook | `hooks`
Milestone | `milestones`
Task | `tasks`
Subscriber | `subscribers`

For example, to get all of the project's users in full and the number of repositories it has, attach `include=users&count=repositories` to your GET request.

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

## Operations

### GET /projects

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

### GET /projects/:id

Returns one project as a project 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

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-06-14T12:06:57Z",
      "id": "luotsi",
      "created_at": "2011-08-23T21:43:20Z",
      "updated_at": "2013-05-11T09:53:09Z",
      "name": "Helix TeamHub",
      "description": "The next generation software development and collaboration hub for the world.",
      "color": "red",
      "labels": [
        "bug",
        "feature",
        "improvement"
      ],
      "visibility": "members",
      "properties": {

      }
    }

### POST /projects

Creates a new project to the company. Returns the created project 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": "platform", "name": "Platform" }' \
      https://helixteamhub.cloud/api/projects

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2013-06-14T12:06:57Z",
      "created_at": "2011-08-23T21:43:20Z",
      "updated_at": "2013-05-11T09:53:09Z",
      "id": "platform",
      "name": "Platform",
      "description": "",
      "color": "red",
      "labels": [

      ],
      "visibility": "members",
      "properties": {

      }
    }

### PUT /projects/:id

Updates a project. Returns the updated project 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 '{ "visibility": "company" }' \
      https://helixteamhub.cloud/api/projects/platform

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2013-06-14T12:06:57Z",
      "created_at": "2011-08-23T21:43:20Z",
      "updated_at": "2013-05-11T09:53:09Z",
      "id": "platform",
      "name": "Platform",
      "description": "",
      "color": "red",
      "labels": [

      ],
      "visibility": "company",
      "properties": {

      }
    }

### DELETE /projects/:id

Deletes a project. Returns the deleted project object.

Your search for returned results

Your search for returned results