API reference

Host groups

5 operations.

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