{"openapi":"3.1.0","info":{"title":"ClickHouse (BYOK) API","version":"0.1.0","description":"ClickHouse (BYOK) lets an AI assistant read your own ClickHouse data through the ClickHouse API with a key you supply (ClickHouse Cloud API key ID). Read-only: 11 tools (list_organizations, get_organization, list_services, get_service, list_backups, get_backup_configuration, get_usage_cost, list_clickpipes, list_postgres_services, list_api_keys, list_activities). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clickhouse.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clickhouse/docs"},"termsOfService":"https://connectorbay.com/byok-clickhouse/terms"},"servers":[{"url":"https://byok-clickhouse.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clickhouse/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_organizations":{"post":{"operationId":"list_organizations","summary":"List the organizations the key belongs to (an API key resolves to its own organization). Use for \"Which ClickHouse Cloud","description":"List the organizations the key belongs to (an API key resolves to its own organization). Use for \"Which ClickHouse Cloud organization does my key belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum number of results to return (default 250; the server may cap it).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from nextCursor of the previous page.","title":"Cursor"}},"title":"list_organizationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_organization":{"post":{"operationId":"get_organization","summary":"Get one organization with its private endpoints, BYOC configuration and capabilities. Use for \"Show details of my ClickH","description":"Get one organization with its private endpoints, BYOC configuration and capabilities. Use for \"Show details of my ClickHouse Cloud organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"}},"required":["organization_id"],"title":"get_organizationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_services":{"post":{"operationId":"list_services","summary":"List all services of the organization with provider, region, state, tier, ClickHouse version, replicas and autoscaling. ","description":"List all services of the organization with provider, region, state, tier, ClickHouse version, replicas and autoscaling. Use for \"Which ClickHouse Cloud services are running and where\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"}},"required":["organization_id"],"title":"list_servicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_service":{"post":{"operationId":"get_service","summary":"Get one service with its state, tier, replica counts, autoscaling and idle settings. Use for \"How is my ClickHouse servi","description":"Get one service with its state, tier, replica counts, autoscaling and idle settings. Use for \"How is my ClickHouse service configured\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"},"service_id":{"description":"ID of the service, as returned by list_services.","maxLength":200,"title":"Service Id","type":"string"}},"required":["organization_id","service_id"],"title":"get_serviceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_backups":{"post":{"operationId":"list_backups","summary":"List the backups of a service, newest first, with status, type, size and duration. Use for \"When was the last successful","description":"List the backups of a service, newest first, with status, type, size and duration. Use for \"When was the last successful backup of my ClickHouse service\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"},"service_id":{"description":"ID of the service, as returned by list_services.","maxLength":200,"title":"Service Id","type":"string"}},"required":["organization_id","service_id"],"title":"list_backupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_backup_configuration":{"post":{"operationId":"get_backup_configuration","summary":"Get the backup schedule of a service: period, retention and start time. Use for \"How often is my ClickHouse service back","description":"Get the backup schedule of a service: period, retention and start time. Use for \"How often is my ClickHouse service backed up and for how long are backups kept\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"},"service_id":{"description":"ID of the service, as returned by list_services.","maxLength":200,"title":"Service Id","type":"string"}},"required":["organization_id","service_id"],"title":"get_backup_configurationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_usage_cost":{"post":{"operationId":"get_usage_cost","summary":"Get the usage cost of the organization in ClickHouse Cloud credits for a date range of at most 31 days, per day and enti","description":"Get the usage cost of the organization in ClickHouse Cloud credits for a date range of at most 31 days, per day and entity. Use for \"What did my ClickHouse Cloud organization spend per service last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"},"from_date":{"description":"Start date of the report, for example 2026-10-01.","maxLength":200,"title":"From Date","type":"string"},"to_date":{"description":"End date (inclusive), at most 30 days after from_date, for example 2026-10-07.","maxLength":200,"title":"To Date","type":"string"}},"required":["organization_id","from_date","to_date"],"title":"get_usage_costArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_clickpipes":{"post":{"operationId":"list_clickpipes","summary":"List the ClickPipes (managed ingestion pipelines) of a service with state, scaling and destination table. Use for \"Are m","description":"List the ClickPipes (managed ingestion pipelines) of a service with state, scaling and destination table. Use for \"Are my ClickPipes running or failing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"},"service_id":{"description":"ID of the service, as returned by list_services.","maxLength":200,"title":"Service Id","type":"string"}},"required":["organization_id","service_id"],"title":"list_clickpipesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_postgres_services":{"post":{"operationId":"list_postgres_services","summary":"List the managed Postgres services of the organization with version, size, HA type, region and state. Use for \"Which man","description":"List the managed Postgres services of the organization with version, size, HA type, region and state. Use for \"Which managed Postgres services do I have in ClickHouse Cloud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"}},"required":["organization_id"],"title":"list_postgres_servicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_api_keys":{"post":{"operationId":"list_api_keys","summary":"List the API keys of the organization with name, state, roles, key suffix, creation, expiry and last use. Secrets are ne","description":"List the API keys of the organization with name, state, roles, key suffix, creation, expiry and last use. Secrets are never returned. Use for \"Which ClickHouse Cloud API keys are unused or about to expire\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum number of results to return (default 250; the server may cap it).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from nextCursor of the previous page.","title":"Cursor"}},"required":["organization_id"],"title":"list_api_keysArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_activities":{"post":{"operationId":"list_activities","summary":"List organization audit activities (key, service, backup and member changes) in a date range. Actor names, e-mails and I","description":"List organization audit activities (key, service, backup and member changes) in a date range. Actor names, e-mails and IP addresses are not returned. Use for \"What changes were made to my ClickHouse Cloud organization this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"description":"ID of the ClickHouse Cloud organization, as returned by list_organizations.","maxLength":200,"title":"Organization Id","type":"string"},"from_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only activities from this date, for example 2026-10-01.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only activities up to this date, for example 2026-10-07.","title":"To Date"}},"required":["organization_id"],"title":"list_activitiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}