API reference · Account and billing
Notifications
4 operations of the Ankra Cloud API: What the control plane told the account: an operation failed, the charge for an invoice failed, the account is about to be or was suspended for an overdue invoice, a create was refused by a limit. A notification is read or unread for the whole account. The ones about billing are also sent by email to the account's owner and admins.
List the account's notifications, newest first#
/v1/notifications- Operation
list_notifications- Credentials
- API token, Portal session
- Requires
- Permission
read
What the control plane told the account, newest first: a failed operation (operation.failed), a failed
charge (billing.payment_failed), the days left before an overdue invoice suspends the account
(billing.suspension_countdown, three days and one day before), the suspension itself
(billing.account_suspended), a create refused by a limit (quota.refused, once a day for each limit), staff
approving or declining a request for higher limits (quota.request_decided), and
for an account with no payment method and no credit that runs servers: the notice that its servers are
powered off seven days later unless a payment method is added (billing.unpaid_usage_found), a reminder
about a day before (billing.unpaid_usage_stop_reminder) and the power-off itself
(billing.unpaid_usage_servers_stopped).
unread=true keeps the ones nobody in the account read yet. Pages hold 50 notifications unless limit asks
for up to 200.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
unread | query | boolean | true keeps only the unread notifications. |
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of notifications.application/json · NotificationList
| Field | Type | Description |
|---|---|---|
itemsrequired | array of Notification | |
idrequired | string | |
kindrequired | string | What the notification is about. New kinds may be added; treat an unknown one as a plain message.One of operation.failed, billing.payment_failed, billing.suspension_countdown, billing.account_suspended, quota.refused, billing.unpaid_usage_found, billing.unpaid_usage_stop_reminder, billing.unpaid_usage_servers_stopped, quota.request_decided |
severityrequired | string | One of info, warning, critical |
titlerequired | string | |
bodyrequired | string | The detail under the title; empty when the title says it all. |
resource_typerequired | string | What the notification is about: operation, invoice or account; empty when it is about nothing in particular. |
resource_idrequired | string | The identifier of that resource. |
created_atrequired | string (date-time) | |
read_atrequired | string (date-time) | null | When somebody in the account first read it; null while unread. |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/notifications' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Mark one notification read#
/v1/notifications/{id}/read- Operation
mark_notification_read- Credentials
- API token, Portal session
- Requires
- Permission
read
Marks the notification read for the whole account and answers it. Marking a read notification again keeps the first read_at. A billing notification (billing.*) needs billing.read as well, and for an API token a scope that includes it: without it the answer is 403 with reason: billing_permission_required. A read-only API token (scope read, or a scope list with neither operate nor billing.manage) is refused with 403. A support session's mark is recorded in the audit log (notification.mark_read).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The notification, read.application/json
| Field | Type | Description |
|---|---|---|
notificationrequired | Notification | |
idrequired | string | |
kindrequired | string | What the notification is about. New kinds may be added; treat an unknown one as a plain message.One of operation.failed, billing.payment_failed, billing.suspension_countdown, billing.account_suspended, quota.refused, billing.unpaid_usage_found, billing.unpaid_usage_stop_reminder, billing.unpaid_usage_servers_stopped, quota.request_decided |
severityrequired | string | One of info, warning, critical |
titlerequired | string | |
bodyrequired | string | The detail under the title; empty when the title says it all. |
resource_typerequired | string | What the notification is about: operation, invoice or account; empty when it is about nothing in particular. |
resource_idrequired | string | The identifier of that resource. |
created_atrequired | string (date-time) | |
read_atrequired | string (date-time) | null | When somebody in the account first read it; null while unread. |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/notifications/<id>/read' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Mark every unread notification of the account read#
/v1/notifications/read-all- Operation
mark_all_notifications_read- Credentials
- API token, Portal session
- Requires
- Permission
read
Clears the bell for the whole account. It takes the read permission, because the read marker changes no resource, but the billing notifications (billing.*) are marked only for a caller who may read the account's billing (billing.read, and for an API token a scope that includes it): for anyone else they stay unread and billing_included is false, so a failed charge or a suspension countdown is not hidden from the people who must act on it. A read-only API token (scope read, or a scope list with neither operate nor billing.manage) is refused with 403. A support session's mark is recorded in the audit log (notification.mark_all_read).
Responses
200How many notifications were marked.application/json
| Field | Type | Description |
|---|---|---|
markedrequired | integer | |
billing_includedrequired | boolean | Whether the billing notifications were marked too. |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/notifications/read-all' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"How many notifications of the account are unread#
/v1/notifications/unread-count- Operation
get_unread_notification_count- Credentials
- API token, Portal session
- Requires
- Permission
read
The number a console shows on its bell. Counting stops at ceiling: an account with more unread notifications answers unread equal to ceiling.
Responses
200The unread count.application/json · NotificationUnreadCount
| Field | Type | Description |
|---|---|---|
unreadrequired | integer | Unread notifications, at most ceiling. |
ceilingrequired | integer | Where counting stops (100). |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/notifications/unread-count' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"