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

• 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.