Host groups
5 operations.
-
GET
/v1/host-groups -
POST
/v1/host-groups -
GET
/v1/host-groups/{host_group_id} -
PATCH
/v1/host-groups/{host_group_id} -
DELETE
/v1/host-groups/{host_group_id}
GET
/v1/host-groups
The account's host groups, by name, each with its members.
- Operation id
listHostGroups- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
hosts.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Answers
200 The host groups. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
host_groups
|
array of object | yes | |
host_groups[]
|
object | yes | |
host_groups[].id
|
string | yes | |
host_groups[].name
|
string | yes | |
host_groups[].description
|
string or null | yes | |
host_groups[].host_ids
|
array of string | yes | The members, sorted. |
host_groups[].version
|
integer | yes | |
host_groups[].created_at
|
string | yes | Limits: format date-time. |
host_groups[].updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 429 | Too many attempts. |
rate_limited
|
POST
/v1/host-groups
Adds a host group. Members are hosts of this account that are not archived. A group may start empty.
- Operation id
createHostGroup- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
hosts.manage - Retry key
- Required: send an Idempotency-Key header.
- Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
Idempotency-Key
|
header | string | yes | Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
name
|
string | yes | |
description
|
string or null | no | Limits: at most 2000 characters. |
host_ids
|
array of string | no |
Answers
201 The host group. application/json
-
Header
Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
name
|
string | yes | |
description
|
string or null | yes | |
host_ids
|
array of string | yes | The members, sorted. |
version
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The body is not valid JSON. The request is not valid. |
invalid_json
,
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 409 | This cannot be done while something else depends on it. The same identifier was already used for a different request. This request is already running. |
conflict
,
id_conflict
,
request_in_progress
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
GET
/v1/host-groups/{host_group_id}
One host group, with its members.
- Operation id
getHostGroup- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
hosts.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
host_group_id
|
path | string | yes | Limits: pattern ^grp_[0-9a-z]{26}$. |
Answers
200 The host group. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
name
|
string | yes | |
description
|
string or null | yes | |
host_ids
|
array of string | yes | The members, sorted. |
version
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 429 | Too many attempts. |
rate_limited
|
PATCH
/v1/host-groups/{host_group_id}
Renames a host group, changes its description, or replaces its members. Send the version you read. A member change that would leave an active event type with no bookable host is refused, and nothing is saved.
- Operation id
updateHostGroup- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
hosts.manage - Assistant tool
- No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
host_group_id
|
path | string | yes | Limits: pattern ^grp_[0-9a-z]{26}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
name
|
string | no | |
description
|
string or null | no | Limits: at most 2000 characters. |
host_ids
|
array of string | no |
Answers
200 The host group after the change. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
name
|
string | yes | |
description
|
string or null | yes | |
host_ids
|
array of string | yes | The members, sorted. |
version
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The body is not valid JSON. The request is not valid. |
invalid_json
,
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This cannot be done while something else depends on it. This was changed by someone else since it was read. |
conflict
,
version_conflict
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
DELETE
/v1/host-groups/{host_group_id}
Deletes a host group, its members and its assignments to event types. Bookings are not touched. Refused while it would leave an active event type with no bookable host.
- Operation id
deleteHostGroup- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
hosts.manage - Assistant tool
- No. It deletes. A delete is never a tool (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
host_group_id
|
path | string | yes | Limits: pattern ^grp_[0-9a-z]{26}$. |
version
|
query | integer | yes | Limits: at least 1. |
Answers
204 The host group has been deleted.
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This cannot be done while something else depends on it. This was changed by someone else since it was read. |
conflict
,
version_conflict
|
| 429 | Too many attempts. |
rate_limited
|