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.