Brands
5 operations.
-
GET
/v1/brands -
POST
/v1/brands -
GET
/v1/brands/{brand_id} -
PATCH
/v1/brands/{brand_id} -
DELETE
/v1/brands/{brand_id}
GET
/v1/brands
The account's brands, the default first, then by name.
- Operation id
listBrands- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Answers
200 The brands. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
brands
|
array of object | yes | |
brands[]
|
object | yes | |
brands[].id
|
string | yes | |
brands[].name
|
string | yes | |
brands[].is_default
|
boolean | yes | The brand of every event type that names none. An account with brands has one. |
brands[].primary_color
|
string | yes | |
brands[].accent_color
|
string or null | yes | |
brands[].sender_name
|
string or null | yes | The name emails are sent under. Null: the account's name. The address stays ours. |
brands[].reply_to_email
|
string or null | yes | Where a visitor's reply goes. Null: the host's own address. |
brands[].version
|
integer | yes | |
brands[].created_at
|
string | yes | Limits: format date-time. |
brands[].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/brands
Adds a brand. The account's first brand is its default. A primary colour the palette rule refuses is refused, with the nearest colour that passes.
- Operation id
createBrand- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.update - 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 | |
primary_color
|
string | yes | #rrggbb. Refused when it is under 3:1 against white or the page background, or when neither white nor dark text reaches 4.5:1 on it; the refusal names the nearest colour that passes. |
accent_color
|
string or null | no | #rrggbb. Tints the selected day and time. Null: a tint of the primary. |
sender_name
|
string or null | no | |
reply_to_email
|
string or null | no | |
is_default
|
boolean | no | Make it the default; the old default stops being it. The account's first brand is the default anyway. |
Answers
201 The brand. 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 | |
is_default
|
boolean | yes | The brand of every event type that names none. An account with brands has one. |
primary_color
|
string | yes | |
accent_color
|
string or null | yes | |
sender_name
|
string or null | yes | The name emails are sent under. Null: the account's name. The address stays ours. |
reply_to_email
|
string or null | yes | Where a visitor's reply goes. Null: the host's own address. |
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/brands/{brand_id}
One brand.
- Operation id
getBrand- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
brand_id
|
path | string | yes | Limits: pattern ^brd_[0-9a-z]{26}$. |
Answers
200 The brand. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
name
|
string | yes | |
is_default
|
boolean | yes | The brand of every event type that names none. An account with brands has one. |
primary_color
|
string | yes | |
accent_color
|
string or null | yes | |
sender_name
|
string or null | yes | The name emails are sent under. Null: the account's name. The address stays ours. |
reply_to_email
|
string or null | yes | Where a visitor's reply goes. Null: the host's own address. |
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/brands/{brand_id}
Changes a brand, or makes it the default. Send the version you read. A primary colour the palette rule refuses is refused, with the nearest colour that passes, and nothing is saved.
- Operation id
updateBrand- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.update - 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 |
|---|---|---|---|---|
brand_id
|
path | string | yes | Limits: pattern ^brd_[0-9a-z]{26}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
name
|
string | no | |
primary_color
|
string | no | #rrggbb. Refused when it is under 3:1 against white or the page background, or when neither white nor dark text reaches 4.5:1 on it; the refusal names the nearest colour that passes. |
accent_color
|
string or null | no | |
sender_name
|
string or null | no | |
reply_to_email
|
string or null | no | |
is_default
|
boolean | no |
true makes this the default brand, and the old default stops being it in the same change. A brand stops being the default only when another one becomes it.
Values:
true
.
|
Answers
200 The brand after the change. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
name
|
string | yes | |
is_default
|
boolean | yes | The brand of every event type that names none. An account with brands has one. |
primary_color
|
string | yes | |
accent_color
|
string or null | yes | |
sender_name
|
string or null | yes | The name emails are sent under. Null: the account's name. The address stays ours. |
reply_to_email
|
string or null | yes | Where a visitor's reply goes. Null: the host's own address. |
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/brands/{brand_id}
Deletes a brand that is not the default. Every event type that named it wears the default brand from then on, each with a new version. The default brand is refused: make another brand the default first.
- Operation id
deleteBrand- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.update - Assistant tool
- No. It deletes. A delete is never a tool (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
brand_id
|
path | string | yes | Limits: pattern ^brd_[0-9a-z]{26}$. |
version
|
query | integer | yes | Limits: at least 1. |
Answers
204 The brand 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
|