Documentation (2024.2 Enterprise)

# Bot

A bot account can be taken into use in multiple projects throughout a company. A bot cannot log into TeamHub, but it can access the TeamHub APIs and source code repositories.

Anyone with access to TeamHub may create bots. The creator automatically becomes the owner of the bot and can assign other users either as members or owners to the bot.

Bots can be created as private or as public. Private bots are only visible to their members and owners, while public bots are visible to everyone.

Bot credentials are only visible to its members and owners and, only bot owners can manage the bot credentials.

Company admin bots can access all projects by default, as well as manage users and groups.

- Attributes
- Related Resources
- Operations
  - `GET /bots`
  - `GET /bots/:id`
  - `POST /bots`
  - `PUT/PATCH /bots/:id`
  - `DELETE /bots/:id`
  - `GET /bots/:bot-id/ssh-keys`
  - `GET /bots/:bot-id/ssh-keys/:id`
  - `POST /bots/:bot-id/ssh-keys`
  - `PUT/PATCH /bots/:bot-id/ssh-keys/:id`
  - `DELETE /bots/:bot-id/ssh-keys/:id`
  - `GET /bots/:bot-id/bot-users`
  - `GET /bots/:bot-id/bot-users/:id`
  - `POST /bots/:bot-id/bot-users`
  - `PUT/PATCH /bots/:bot-id/bot-users/:id`
  - `DELETE /bots/:bot-id/bot-users/:id`

## Attributes

### short-name

A URL-friendly identifier. Also used as the bot's version control username.

- Type: `string`
- Required: `true`
- Unique: `true` (within company)
- Minimum length: `2`
- Maximum length: `40`
- Allowed characters: `a-z`, `A-Z`, `0-9`, `-`, `_`

### password

The bot's password. Used for version control access. When creating a bot, TeamHub automatically generates a password if you do not provide one. When updating a bot, leave empty if you do not want to change it. Validations depend on instance-specific configurations.

- Type: `string`
- Default minimum length: `8`
- Default maximum length: `100`
- Required: `false`

### visibility

- Type: `string`
- Required: `false`
- Default: `private`
- Allowed values: `private`, `public`

Company admin bots are always public.

### company-admin

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

## Related Resources

The following related resources can be attached to the bots returned, to eliminate the need for requesting them separately:

Object | Attribute
--- | ---
SSH Keys | `ssh-keys`
Users> | `bot-users`

For example, to get all of the bot's SSH keys in full, attach `include=ssh-keys,bot-users` to your GET request.

## Operations

### GET /bots

Returns all bots in the company.

### GET /bots/:id

Returns the bot as a bot object.

### POST /bots

Creates a new bot. Returns the bot object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.api+json" \
      -H "Content-Type: application/vnd.api+json" \
      -d '{ "data": { "attributes": { "short-name": "hth-bot" } } }' \
      http://dev.helixteamhub.com/api/v2/bots?account_key=$ACCOUNT_KEY

#### Example Response

    {
      "data": {
        "id": "61daa045-2ce7-42bb-8d30-c89b736090c1",
        "type": "bots",
        "attributes": {
          "short-name": "hth-bot",
          "password": "iE%1UzWOS-k_jjIa_w78",
          "company-admin": false,
          "account-key": "4aed6ec3e0b1010c427659099fb0b6bc",
          "visibility": "private",
          "created-at": "2016-02-04T16:04:41.283Z",
          "updated-at": "2016-02-04T16:04:41.283Z"
        },
        "relationships": {
          "creator": {
            "data": {
              "id": "fdd36536-8a08-4e5b-ab25-6f7c975c9212",
              "type": "users"
            }
          },
          "company": {
            "data": {
              "id": "ba64aeb7-d9ba-4a8e-a3aa-f9352d224f6a",
              "type": "companies"
            }
          },
          "ssh-keys": {
            "data": []
          },
          "bot-users": {
            "data": [{
              "id": "61daa045-2ce7-42bb-8d30-c89b736090c1_fdd36536-8a08-4e5b-ab25-6f7c975c9212",
              "type": "bot-users"
            }]
          }
        }
      }
    }

### PUT/PATCH /bots/:id

Updates the existing bot. Returns the updated bot object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.api+json" \
      -H "Content-Type: application/vnd.api+json" \
      -d '{ "data": { "attributes": { "visibility": "public", "short-name": "public-hth-bot" } } }' \
      http://dev.helixteamhub.com/api/v2/bots/61daa045-2ce7-42bb-8d30-c89b736090c1?account_key=$ACCOUNT_KEY

#### Example Response

    {
      "data": {
        "id": "61daa045-2ce7-42bb-8d30-c89b736090c1",
        "type": "bots",
        "attributes": {
          "short-name": "public-hth-bot",
          "password": "iE%1UzWOS-k_jjIa_w78",
          "company-admin": false,
          "account-key": "4aed6ec3e0b1010c427659099fb0b6bc",
          "visibility": "public",
          "created-at": "2016-02-04T16:04:41.283Z",
          "updated-at": "2016-02-04T16:10:36.532Z"
        },
        "relationships": {
          "creator": {
            "data": {
              "id": "fdd36536-8a08-4e5b-ab25-6f7c975c9212",
              "type": "users"
            }
          },
          "company": {
            "data": {
              "id": "ba64aeb7-d9ba-4a8e-a3aa-f9352d224f6a",
              "type": "companies"
            }
          },
          "ssh-keys": {
            "data": []
          },
          "bot-users": {
            "data": [{
              "id": "61daa045-2ce7-42bb-8d30-c89b736090c1_fdd36536-8a08-4e5b-ab25-6f7c975c9212",
              "type": "bot-users"
            }]
          }
        }
      }
    }

### DELETE /bots/:id

Deletes the existing bot. Returns a 204 status code and blank response.

### GET /bots/:bot-id/ssh-keys

Returns all SSH keys added to the bot.

### GET /bots/:bot-id/ssh-keys/:id

Returns the SSH key added to the bot as an SSH key object.

### POST /bots/:bot-id/ssh-keys

Creates and adds an SSH key to the bot. Returns the SSH key object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.api+json" \
      -H "Content-Type: application/vnd.api+json" \
      -d '{ "data": { "attributes": { "title": "hth-bot-ssh-key", "content": "ssh-rsa ... user@machine" } } }' \
      http://dev.helixteamhub.com/api/v2/bots/61daa045-2ce7-42bb-8d30-c89b736090c1/ssh-keys?account_key=$ACCOUNT_KEY

#### Example Response

    {
      "data": {
        "id": "73ca16c5-627c-4373-9e10-8e435cbc62eb",
        "type": "ssh-keys",
        "attributes": {
          "title": "hth-bot-ssh-key",
          "body": "ssh-rsa ... user@machine",
          "created-at": "2016-02-04T16:29:33.303Z",
          "updated-at": "2016-02-04T16:29:33.303Z"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "61daa045-2ce7-42bb-8d30-c89b736090c1",
              "type": "bots"
            }
          }
        }
      }
    }

### PUT/PATCH /bots/:bot-id/ssh-keys/:id

Updates the existing SSH key. Returns the updated SSH key object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.api+json" \
      -H "Content-Type: application/vnd.api+json" \
      -d '{ "data": { "attributes": { "title": "hth-bot-ssh-key-updated", "content": "ssh-rsa ... user@machine" } } }' \
      http://dev.helixteamhub.com/api/v2/bots/61daa045-2ce7-42bb-8d30-c89b736090c1/ssh-keys/73ca16c5-627c-4373-9e10-8e435cbc62eb?account_key=$ACCOUNT_KEY

#### Example Response

    {
      "data": {
        "id": "73ca16c5-627c-4373-9e10-8e435cbc62eb",
        "type": "ssh-keys",
        "attributes": {
          "title": "hth-bot-ssh-key-updated",
          "body": "ssh-rsa ... user@machine",
          "created-at": "2016-02-04T16:29:33.303Z",
          "updated-at": "2016-02-04T16:39:00.143Z"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "61daa045-2ce7-42bb-8d30-c89b736090c1",
              "type": "bots"
            }
          }
        }
      }
    }

### DELETE /bots/:bot-id/ssh-keys/:id

Removes the SSH key. Returns 204 status code and blank response.

### GET /bots/:bot-id/bot-users

Returns all users added to the bot as bot-users objects.

### GET /bots/:bot-id/bot-users/:id

Returns the user added to the bot as a bot-user object.

### POST /bots/:bot-id/bot-users

Adds a user to the bot. Does not create a new user. Returns the bot-user object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.api+json" \
      -H "Content-Type: application/vnd.api+json" \
      -d '{ "data": { "attributes": { "role": "member" }, "relationships": { "user": { "data": { "id": "ef5e59d0-990a-4a43-83af-e2db0bbf080a" } } } } }' \
      http://dev.helixteamhub.com/api/v2/bots/61daa045-2ce7-42bb-8d30-c89b736090c1/bot-users?account_key=$ACCOUNT_KEY

#### Example Response

    {
      "data": {
        "id": "61daa045-2ce7-42bb-8d30-c89b736090c1_ef5e59d0-990a-4a43-83af-e2db0bbf080a",
        "type": "bot-users",
        "attributes": {
          "role": "member"
        },
        "relationships": {
          "bot": {
            "data": {
              "id": "61daa045-2ce7-42bb-8d30-c89b736090c1",
              "type": "bots"
            }
          },
          "user": {
            "data": {
              "id": "ef5e59d0-990a-4a43-83af-e2db0bbf080a",
              "type": "users"
            }
          }
        }
      }
    }

### PUT/PATCH /bots/:bot-id/bot-users/:id

Updates the existing bot-user. Returns the updated bot-user object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.api+json" \
      -H "Content-Type: application/vnd.api+json" \
      -d '{ "data": { "attributes": { "role": "owner" } } }' \
      http://dev.helixteamhub.com/api/v2/bots/61daa045-2ce7-42bb-8d30-c89b736090c1/bot-users/61daa045-2ce7-42bb-8d30-c89b736090c1_ef5e59d0-990a-4a43-83af-e2db0bbf080a?account_key=$ACCOUNT_KEY

#### Example Response

    {
      "data": {
        "id": "61daa045-2ce7-42bb-8d30-c89b736090c1_ef5e59d0-990a-4a43-83af-e2db0bbf080a",
        "type": "bot-users",
        "attributes": {
          "role": "owner"
        },
        "relationships": {
          "bot": {
            "data": {
              "id": "61daa045-2ce7-42bb-8d30-c89b736090c1",
              "type": "bots"
            }
          },
          "user": {
            "data": {
              "id": "ef5e59d0-990a-4a43-83af-e2db0bbf080a",
              "type": "users"
            }
          }
        }
      }
    }

### DELETE /bots/:bot-id/bot-users/:id

Removes the user from the bot. Returns a 204 status code and blank response.

Your search for returned results

Your search for returned results