init API docs

zamazan4ik · May 1, 2023 · abb8404 · abb8404
1 parent ac20249
commit abb8404
Show file tree

Hide file tree

Showing 7 changed files with 1,258 additions and 0 deletions.
diff --git a/docs/en/cloud/manage/api/api-overview.md b/docs/en/cloud/manage/api/api-overview.md
@@ -0,0 +1,24 @@
+---
+sidebar_label: Overview
+---
+
+# ClickHouse Cloud API
+
+## Overview
+
+The ClickHouse Cloud API is a REST API designed for developers to easily manage organizations and services on ClickHouse Cloud. Using our Cloud API, you can create and manage services, provision API keys, add or remove members in your organization, and more.
+
+[Learn how to create your first API key and start using the ClickHouse Cloud API.](https://clickhouse.com/docs/en/cloud/manage/openapi)
+
+## Rate Limits
+
+Developers are limited to 5 API keys per organization. Each API key has a limit of 10 requests over a 10 second window. If you'd like to increase the number of API keys or requests per 10 second window for your organization, please contact [email protected]
+
+
+## Terraform API
+
+Our Terraform API is coming soon and we're looking for beta testers. If you're interested in trying out our Terraform API to programatically provision services, please contact [email protected].
+
+## Support
+
+We recommend visiting [our Slack channel](https://clickhouse.com/slack) first to get quick support. If you'd like additional help or more info about our API and its capabilities, please contact [email protected].
diff --git a/docs/en/cloud/manage/api/invitations-api-reference.md b/docs/en/cloud/manage/api/invitations-api-reference.md
@@ -0,0 +1,151 @@
+---
+sidebar_label: Invitations
+---
+
+## List all invitations
+
+Returns list of all organization invitations.
+
+| Method | Path |
+| :----- | :--- |
+| GET | /v1/organizations/:organizationId/invitations |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+
+
+### Response
+
+#### Response Schema
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| role | string | Role of the member in the organization. | 
+| id | string | Unique invitation ID. | 
+| email | string | Email of the invited user. Only a user with this email can join using the invitation. The email is stored in a lowercase form. | 
+| createdAt | string | Invitation creation timestamp. ISO-8601. | 
+| expiresAt | string | Timestamp the invitation expires. ISO-8601. | 
+
+#### Sample response
+
+```
+{
+  "role": "string",
+  "id": "string",
+  "email": "string",
+  "createdAt": "string",
+  "expiresAt": "string"
+}
+```
+
+## Create an invitation
+
+Creates organization invitation.
+
+| Method | Path |
+| :----- | :--- |
+| POST | /v1/organizations/:organizationId/invitations |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+
+#### Body Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| email | string | Email of the invited user. Only a user with this email can join using the invitation. The email is stored in a lowercase form. | 
+| role | string | Role of the member in the organization. | 
+
+### Response
+
+#### Response Schema
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| role | string | Role of the member in the organization. | 
+| id | string | Unique invitation ID. | 
+| email | string | Email of the invited user. Only a user with this email can join using the invitation. The email is stored in a lowercase form. | 
+| createdAt | string | Invitation creation timestamp. ISO-8601. | 
+| expiresAt | string | Timestamp the invitation expires. ISO-8601. | 
+
+#### Sample response
+
+```
+{
+  "role": "string",
+  "id": "string",
+  "email": "string",
+  "createdAt": "string",
+  "expiresAt": "string"
+}
+```
+
+## Get invitation details
+
+Returns details for a single organization invitation.
+
+| Method | Path |
+| :----- | :--- |
+| GET | /v1/organizations/:organizationId/invitations/:invitationId |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+| Organization invitation ID | string |  | 
+
+
+### Response
+
+#### Response Schema
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| role | string | Role of the member in the organization. | 
+| id | string | Unique invitation ID. | 
+| email | string | Email of the invited user. Only a user with this email can join using the invitation. The email is stored in a lowercase form. | 
+| createdAt | string | Invitation creation timestamp. ISO-8601. | 
+| expiresAt | string | Timestamp the invitation expires. ISO-8601. | 
+
+#### Sample response
+
+```
+{
+  "role": "string",
+  "id": "string",
+  "email": "string",
+  "createdAt": "string",
+  "expiresAt": "string"
+}
+```
+
+## Delete organization invitation
+
+Deletes a single organization invitation.
+
+| Method | Path |
+| :----- | :--- |
+| DELETE | /v1/organizations/:organizationId/invitations/:invitationId |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+| Organization invitation ID | string |  | 
+
diff --git a/docs/en/cloud/manage/api/keys-api-reference.md b/docs/en/cloud/manage/api/keys-api-reference.md
@@ -0,0 +1,217 @@
+---
+sidebar_label: Keys
+---
+
+## Get list of all keys
+
+Returns a list of all keys in the organization.
+
+| Method | Path |
+| :----- | :--- |
+| GET | /v1/organizations/:organizationId/keys |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+
+
+### Response
+
+#### Response Schema
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| id | string | Unique API key ID. | 
+| name | string | Name of the key | 
+| state | string | State of the key: 'enabled', 'disabled'. | 
+| roles | array | List of roles assigned to the key. Contains at least 1 element. | 
+| keySuffix | string | Last 4 letters of the key. | 
+| createdAt | string | Timestamp the key was created. ISO-8601. | 
+| expiresAt | string | Timestamp the key expires. If not present or is empty the key never expires. ISO-8601. | 
+| usedAt | string | Timestamp the key was used last time. If not present the key was never used. ISO-8601. | 
+
+#### Sample response
+
+```
+{
+  "id": "string",
+  "name": "string",
+  "state": "string",
+  "roles": "Array",
+  "keySuffix": "string",
+  "createdAt": "string",
+  "expiresAt": "string",
+  "usedAt": "string"
+}
+```
+
+## Create key
+
+Creates new API key.
+
+| Method | Path |
+| :----- | :--- |
+| POST | /v1/organizations/:organizationId/keys |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+
+#### Body Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| name | string | Name of the key. | 
+| expiresAt | string | Timestamp the key expires. If not present or is empty the key never expires. ISO-8601. | 
+| state | string | Initial state of the key: 'enabled', 'disabled'. If not provided the new key will be 'enabled'. | 
+| hashData | undefined |  | 
+| roles | array | List of roles assigned to the key. Contains at least 1 element. | 
+
+### Response
+
+#### Response Schema
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| key | undefined |  | 
+| keyId | string | Generated key id. Provided only if there was no 'hashData' in the request. | 
+| keySecret | string | Generated key secret. Provided only if there was no 'hashData' in the request. | 
+
+#### Sample response
+
+```
+{
+  "keyId": "string",
+  "keySecret": "string"
+}
+```
+
+## Get key details
+
+Returns a single key details.
+
+| Method | Path |
+| :----- | :--- |
+| GET | /v1/organizations/:organizationId/keys/:keyId |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+| API key ID | string |  | 
+
+
+### Response
+
+#### Response Schema
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| id | string | Unique API key ID. | 
+| name | string | Name of the key | 
+| state | string | State of the key: 'enabled', 'disabled'. | 
+| roles | array | List of roles assigned to the key. Contains at least 1 element. | 
+| keySuffix | string | Last 4 letters of the key. | 
+| createdAt | string | Timestamp the key was created. ISO-8601. | 
+| expiresAt | string | Timestamp the key expires. If not present or is empty the key never expires. ISO-8601. | 
+| usedAt | string | Timestamp the key was used last time. If not present the key was never used. ISO-8601. | 
+
+#### Sample response
+
+```
+{
+  "id": "string",
+  "name": "string",
+  "state": "string",
+  "roles": "Array",
+  "keySuffix": "string",
+  "createdAt": "string",
+  "expiresAt": "string",
+  "usedAt": "string"
+}
+```
+
+## Update key
+
+Updates API key properties.
+
+| Method | Path |
+| :----- | :--- |
+| PATCH | /v1/organizations/:organizationId/keys/:keyId |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+| API key ID | string |  | 
+
+#### Body Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| name | string | Name of the key | 
+| roles | array | List of roles assigned to the key. Contains at least 1 element. | 
+| expiresAt | string | Timestamp the key expires. If not present or is empty the key never expires. ISO-8601. | 
+| state | string | State of the key: 'enabled', 'disabled'. | 
+
+### Response
+
+#### Response Schema
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| id | string | Unique API key ID. | 
+| name | string | Name of the key | 
+| state | string | State of the key: 'enabled', 'disabled'. | 
+| roles | array | List of roles assigned to the key. Contains at least 1 element. | 
+| keySuffix | string | Last 4 letters of the key. | 
+| createdAt | string | Timestamp the key was created. ISO-8601. | 
+| expiresAt | string | Timestamp the key expires. If not present or is empty the key never expires. ISO-8601. | 
+| usedAt | string | Timestamp the key was used last time. If not present the key was never used. ISO-8601. | 
+
+#### Sample response
+
+```
+{
+  "id": "string",
+  "name": "string",
+  "state": "string",
+  "roles": "Array",
+  "keySuffix": "string",
+  "createdAt": "string",
+  "expiresAt": "string",
+  "usedAt": "string"
+}
+```
+
+## Delete key
+
+Deletes API key. Only a key not used to authenticate the active request can be deleted.
+
+| Method | Path |
+| :----- | :--- |
+| DELETE | /v1/organizations/:organizationId/keys/:keyId |
+
+### Request
+
+#### Path Params
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+| Organization ID | string |  | 
+| API key ID | string |  | 
+