ClickHouse Notifications API
The Notifications API from ClickHouse — 2 operation(s) for notifications.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/clickhouse:clickhouse-notifications-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: OpenAPI spec for ClickHouse Cloud Notifications API
version: '1.0'
contact:
name: ClickHouse Support
url: https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1256081
email: support@clickhouse.com
servers:
- url: https://api.clickhouse.cloud
security:
- basicAuth: []
tags:
- name: Notifications
paths:
/v1/organizations/{organizationId}/notifications:
get:
summary: List of organization notifications
description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change.
Returns notifications for the organization, most recent first. Only notifications about resources the caller can access are returned, so two keys in the same organization can see different results. The notification types endpoint lists the types this organization can receive, so it shows what to expect here. Notifications are retained for 180 days. A page holds at most `limit` notifications (default 100, maximum 250; a larger value is clamped) and the server may return fewer. Every response carries `limit` and `nextCursor`; pass `nextCursor` as the `cursor` query parameter to fetch the next page, repeating until it is null.'
operationId: notificationGetList
parameters:
- in: path
name: organizationId
description: ID of the organization the notifications belong to.
required: true
schema:
type: string
format: uuid
- in: query
name: limit
description: Maximum number of results to return.
schema:
type: integer
minimum: 1
maximum: 250
default: 100
- in: query
name: cursor
description: Opaque cursor from a previous response's `nextCursor`, marking where to resume the list.
schema:
type: string
- in: query
name: severity
description: 'Filter to notifications of this severity: ''info'', ''warning'', ''critical''.'
schema:
type: string
example: warning
- in: query
name: type
description: Filter to notifications of this type. New types are added over time; the [notification types endpoint](#tag/Notifications/operation/notificationTypesGetList) lists the ones this organization can receive.
schema:
type: string
- in: query
name: resource_id
description: Filter to notifications about this resource. A service also matches the notifications of its ClickPipes; pass `resource_type` to narrow to one kind of resource.
schema:
type: string
- in: query
name: resource_type
description: Filter to notifications about resources of this kind. One of 'service', 'organization', 'clickpipe', 'postgres'.
schema:
type: string
example: service
- in: query
name: from_date
description: Return notifications created at or after this time. An RFC 3339 timestamp, not a bare date.
schema:
type: string
format: date-time
example: '2026-10-01T00:00:00Z'
- in: query
name: to_date
description: Return notifications created at or before this time. An RFC 3339 timestamp, not a bare date.
schema:
type: string
format: date-time
example: '2026-10-08T00:00:00Z'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 200
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
result:
type: array
items:
$ref: '#/components/schemas/Notification'
limit:
type: integer
description: Maximum number of results returned in this page.
nextCursor:
type:
- string
- 'null'
description: Cursor for the next page, to be sent as the `cursor` query parameter. Null on the last page.
'400':
description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 400
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
'500':
description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code.
example: 500
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
tags:
- Notifications
x-badges:
- name: Beta
position: after
/v1/organizations/{organizationId}/notificationTypes:
get:
summary: List notification types
description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change.
Returns every notification type the organization is entitled to, each flagged with whether the caller may use it. Types the organization is not entitled to are omitted; types the caller lacks permission to use are returned with `isAvailable` set to false. Every type supports the `ui`, `email` and `slack` channels, so channels are a property of the API rather than of a type. The effective delivery default is a function of type, role and channel, so no per-type default is reported here.'
operationId: notificationTypesGetList
parameters:
- in: path
name: organizationId
description: ID of the requested organization.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 200
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
result:
type: array
items:
$ref: '#/components/schemas/NotificationType'
'400':
description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 400
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
'500':
description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code.
example: 500
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
security:
- basicAuth:
- control-plane:organization:view
tags:
- Notifications
x-badges:
- name: Beta
position: after
components:
schemas:
NotificationType:
properties:
name:
description: Stable identifier of the notification type. Never renamed or reused.
type: string
example: service_backup_failed
title:
description: Human-readable name of the notification type.
type: string
example: Backup failed
description:
description: Longer explanation of what the notification reports. Omitted for types that have none.
type: string
category:
description: 'Broad grouping the notification type belongs to. Current values: billing, service, clickpipe, postgres. New values may be added over time.'
type: string
example: service
severity:
description: Relative importance of notifications of this type.
type: string
enum:
- info
- warning
- critical
example: warning
resourceType:
description: 'Kind of resource a notification of this type is about. Current values: service, organization, clickpipe, postgres. New values may be added over time.'
type: string
example: service
isConfigurable:
description: Whether the per-role delivery default can be changed. When false the role default is frozen; this does not mean the notification is always delivered.
type: boolean
isAvailable:
description: False when the caller lacks the permission this type requires. The type is still returned, just flagged.
type: boolean
required:
- name
- title
- category
- severity
- resourceType
- isConfigurable
- isAvailable
Notification:
properties:
id:
description: Unique notification ID.
type: string
format: uuid
example: 1b7e0a94-2d0f-4c3a-8f1e-6c9b2d5a4e7f
type:
description: Notification type. New types are added over time, so treat this as an open set.
type: string
example: service_backup_failed
severity:
description: Severity of the notification. One of 'info', 'warning', 'critical'.
type: string
example: warning
resourceType:
description: Kind of resource the notification is about. One of 'service', 'organization', 'clickpipe', 'postgres'.
type: string
example: service
resourceId:
description: ID of the resource the notification is about.
type: string
resourceName:
description: Name the resource had when the notification was created. Absent for most notification types; use `resourceId` to identify the resource.
type: string
createdAt:
description: When the notification was created. ISO-8601.
type: string
format: date-time
example: '2026-10-07T09:30:00Z'
title:
description: Short human-readable summary.
type: string
example: Backup failed for analytics-prod
description:
description: Human-readable body as plain text, with any links written as "label (url)".
type: string
example: A scheduled backup for analytics-prod did not complete. Review the backup settings (https://console.clickhouse.cloud/services/abc/backups).
required:
- id
- type
- severity
- resourceType
- resourceId
- createdAt
- title
- description
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi'
x-permission-scopes: The scope list of a `security` requirement holds ClickHouse Cloud API key permission ids (for example `control-plane:organization:view`), not OAuth scopes. OpenAPI has no field for API key permissions, so this is the closest available place. A key must hold every permission listed on an operation to call it; an operation with no scopes needs none beyond a valid key. Every operation declares at most one requirement object, always for this scheme, so the list is only ever conjunctive — alternative sets of permissions are never expressed.
x-tagGroups:
- name: Organization
tags:
- Organization
- Notifications
- Billing
- User management
- Role Management
- UDF
- name: Service
tags:
- Service
- Backup
- Snapshot
- Query API endpoints
- Saved queries
- name: API keys
tags:
- API keys
- name: Prometheus
tags:
- Prometheus
- name: ClickPipes
tags:
- ClickPipes
- name: ClickStack
tags:
- ClickStack
- name: Postgres
tags:
- Postgres