Helix TeamHub API v1

This is the home of stable Helix TeamHub RESTful API documentation. There is also another API version documented - the experimental v2.

On these pages you'll find everything you need to know about the Helix TeamHub REST APIs. These give you access to all the data Helix TeamHub stores, and you will be able to build any clients and integrations you need.

This page introduces the general concepts used throughout all Helix TeamHub APIs, from authentication to the calling conventions and the error codes. To get information about specific types of data, use the navigation on the right.

API version

By default, all requests to Helix TeamHub APIs use the latest version, however, we recommend you to explicitly request the wanted version via the Accept header.

Accept: application/vnd.hth.v1

API stability

Helix TeamHub APIs follow semantic versioning but only the major version number is used. Bug fixes and backwards compatible changes can be added to the same major version. Major Helix TeamHub releases may deprecate older version of APIs and introduce a new version, e.g.


All requests (except login/logout) require the following set of keys to be present:

If you don't know your Company key and Account key, you can acquire them by authenticating with your company ID, login (email or user ID) and password:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.hth.v1" \
  -d '{"company": "acme", "login": "chuck@norris.com", "password": "ChuckN0rr!5" }' \

You will find the account_key, company_key and details of the account (that is either User or Collaborator) and company in the response:

  "api_status": 201,
  "api_timestamp": "2014-12-02T12:26:01Z",
  "account_key": "ab187f75aa6322eff512bfe8ef97b292",
  "company_key": "553ae10f609b0a0d8ac9ebcceefb8d21",
  "account": {
  "company": {

You can use this same mechanism to implement Helix TeamHub authentication into your own tools and scripts: Prompt the user for their company, login (email or user ID) and password, and then execute the authentication request on their behalf. Then you can execute any other requests for them by using their account key and company key.

Finally, to logout the user permanently, you can invalidate the account_key with:

curl -X DELETE \
  -H "Accept: application/vnd.hth.v1" \


Authorization is always done before you attempt to do anything via our APIs. However, sometimes you end up in a situation where you would like to know beforehand what you or the current user of your application has privileges to do in Helix TeamHub, e.g. to build a better user experience by hiding specific UI components and whatnot.

Luckily, Helix TeamHub has just what you need to accomplish this; we call them privileges. To read the privileges for a collection of objects or for a specific object is trivial and nearly all of our endpoints support the behavior. Basically all you need to do is to append one query parameter, namely privileges, to your RESTful requests and you're done.

Please note that the response for a collection of objects and for a specific object slightly differs. This is due to the fact that there isn't a point in asking whether or not one could update or delete a collection of objects, as such operations are always done against a specific object. To clear it up, we've provided you with some examples, you'll find them below.

Can I create and/or read projects in my company?

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "create": true,
  "read": true

Can I read, update, and/or delete the "platform" project in my company?

curl -X GET \
  -H "Accept: application/vnd.hth.v1" \
  -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
  "api_status": 200,
  "api_timestamp": "2014-01-10T08:05:03Z",
  "read": true,
  "update": true,
  "delete": true

Data objects

Here are the data objects you can access through the Helix TeamHub APIs, and the operations you can execute on them.

Each object, whatever its type, has an id attribute, which is its identifier and unique within the object type. That identifier can be used to refer to the object in other contexts.

Object Create Show List Update Destroy
Code Review
Group Member
Hook Service
Password Recovery
Project Collaborator
Project Group
Project Member
Project User

HTTP methods

The API endpoints are used with the following HTTP methods:

Parameter nesting

All API endpoints support both nested and non-nested request parameters for POST and PUT requests. What this means is that you can do

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": "norris", "email": "norris@helixteamhub.com" }' \

instead of

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 '{ "user": { "id": "norris", "email": "norris@helixteamhub.com" } }' \

While the latter example still works, consider the non-nested form the official one for v1.

Attribute types

The data objects may have attributes with the following types:




"Åbo Akademi"




A timestamp in the ISO-8601 format (always UTC). Milliseconds are not included.



A list of other values.

  "Chuck Norris",
  "Clark Kent"


Another, nested API object.

  id: "norris",
  first_name: "Chuck",

Common attributes

Every API object has the following attributes:


The HTTP status code that describes the response status for this specific object.

When handling only one object, this is always the same as the status code in the HTTP header. However, with multiple objects each one might have a different status code. For instance, there may be a situation where half of a batch of objects could not be created.

api_status: 422


The point in time when the response was created. As the state of the API objects can change, this timestamps each request so you know how recent the information is.

Note that with heavy requests, the returned objects might have API timestamps that differ from each other.

api_timestamp: "2012-01-22T22:11:11Z"

Most of the API objects have the following attributes:


The point in time when the object was created.

created_at: "2012-01-22T22:11:11Z"


The point in time when the object was last updated.

updated_at: "2012-01-22T22:11:11Z"

Custom attributes

Some of the API objects allow storing custom attributes within the object using the properties attribute.

"properties": {
  "string": "value",
  "array": [
  "object": {
    "nested": "value"

Attributes in deactivated objects

When you delete an object in Helix TeamHub, it will usually be a "soft delete", where the object is not actually physically deleted, just deactivated. (Notable exceptions to this rule are project users, project groups, groups, group members, hooks and SSH keys).

When an object has been deactivated, you are still able to access it through the show endpoint, but you may not modify or restore it. When an object is deactivated, its identifier is renamed. For instance, from norris to norris-1234567.

All deactivated objects have two extra attributes:


Time of the deletion.

deleted_at: "2013-01-18T09:13:55Z"


Value of the original identifier before deletion.

old_id: "norris"

Error responses

Errors caused by API requests are identifiable by the HTTP status codes that are returned along with the responses. In an error situation, the API response includes the following attributes within the (invalid) API object:


HTTP status code.

api_status: 404


HTTP status message.

api_message: "Not Found"


Related validation errors, grouped by attribute. See the next section for details.

  email: {
    invalid: true,
    conflicts: ["password"]
  password: {
    conflicts: ["email"]

Validation errors

When you try to create or update one or more objects and some of them are invalid, the API responds with the HTTP status code 422 Unprocessable Entity. The objects in the response have an api_errors attribute, which includes all the validation errors grouped by attribute.

Different field types may have different kinds of validation errors (see the object-specific references for details):


The given value is too short (strings), too low (int), or doesn't contain enough objects (arrays). The response contains the minimum value required.

minimum: 10


The given value is too long (strings), too high (int), or contains too many objects (arrays). The response contains the maximum value required.

maximum: 40


The given value cannot be used with one or more of the other given values. In this case, these other attributes are also returned as incompatible. The array contains the names of the conflicting attributes.

conflicts: ["email"]


The value for this attribute cannot be an empty string, 0 or false.

empty: true


The given value contains the characters that are not allowed, is of invalid type/format, or is otherwise illegal.

invalid: true


The given value is already in use or reserved for something else.

reserved: true


The referenced object was not found

not_found: true


The given value can not be changed. Depending on the object type, some other user with different privileges might be able to change the value.

locked: true

Limiting results

The results of all list actions may be limited for purposes of paging or progressive loading. The responses have the following form:

  "metadata": {
    "more_results": true,
    "next_offset": 2,
    "count": 2
  "results": [
     "key": "value"
     "key": "value"

The result is an object with two keys:

To limit the returned results of a request, pass the following arguments as query parameters in the request:


Limits the amount of results returned. Use this to speed up the request when you know you don't need more than N results.


Moves the starting point of the returned array from zero to the given number. Use this together with limit to implement pagination or other index-based result grouping.


Limits returned data to include only objects that were updated before the given point in time.


Limits returned data to include only objects that were updated after the given point in time.


By default only active objects are returned from the index endpoint. Use this flag to explicitly request deactivated objects.



A search term to look for. Use together with search_fields.


Optionally limit the attributes to search, by default all the searchable attributes of the object are used. Use together with search_term. Refer to the object specific references to see the supported searchable attributes.

Sorting results

To sort results, pass the following arguments as query parameters in your request:


The results are ordered naturally based on the value of the given attribute.


Sorts the results from low to high or high to low. Use together with order.

Child objects

When requesting objects that may have child objects related to them (for example, Projects may have Repositories), you can combine the fetching of those child objects to a single request. This can be done on several levels: You can count the child objects, get their IDs, or get them in full.

Refer to object-specific documentation for the possible child objects.


Count the numbers of child objects the requested object has. Specify the names of the attributes.

repositories: 32,
users: 15


List the IDs of child objects the requested object has. Specify the names of the attributes.

repositories: ["amiraali", "luotsi"]


Return child objects in full. Specify the names of the attributes.

repositories: [
    id: "amiraali",
    type: "git",


Return linked objects in full. Specify the names of the attributes.

You can use expand in cases where the default behavior of the API is to specify an ID of a linked object, to expand the id to the linked object's full representation.

subject: {
  id: username,
  email: email@email.com,
Updated on: 15 December 2017