{"id":28959561,"url":"https://github.com/qdrant/qdrant-cloud-public-api","last_synced_at":"2026-05-13T13:02:28.633Z","repository":{"id":298475244,"uuid":"924678247","full_name":"qdrant/qdrant-cloud-public-api","owner":"qdrant","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-08T16:09:01.000Z","size":4618,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-12-09T01:03:37.876Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qdrant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-30T13:04:15.000Z","updated_at":"2025-12-08T10:10:35.000Z","dependencies_parsed_at":"2025-06-11T10:00:00.105Z","dependency_job_id":"b431961f-d2d1-469c-93b8-e801844cc45e","html_url":"https://github.com/qdrant/qdrant-cloud-public-api","commit_stats":null,"previous_names":["qdrant/qdrant-cloud-public-api"],"tags_count":108,"template":false,"template_full_name":null,"purl":"pkg:github/qdrant/qdrant-cloud-public-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrant%2Fqdrant-cloud-public-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrant%2Fqdrant-cloud-public-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrant%2Fqdrant-cloud-public-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrant%2Fqdrant-cloud-public-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qdrant","download_url":"https://codeload.github.com/qdrant/qdrant-cloud-public-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrant%2Fqdrant-cloud-public-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27764777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-24T00:02:07.882Z","updated_at":"2026-05-13T13:02:28.621Z","avatar_url":"https://github.com/qdrant.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Qdrant Cloud API\n\nWelcome to the Qdrant Cloud API [repository](https://github.com/qdrant/qdrant-cloud-public-api)!\n\n## Introduction\n\nThis repository hosts the Protocol Buffer (`.proto`) definitions that define the contract for interacting with Qdrant Cloud platform services.\n\nThe Qdrant Cloud API offers two main ways to interact:\n\n* **gRPC:** For high-performance, type-safe communication, ideal for backend services and (newer) clients.\n* **REST/JSON:** A conventional HTTP/1.1 (and HTTP/2) based interface with JSON payloads, provided via gRPC Gateway for ease of use with tools.\n\nThis repository also contains generated client libraries (SDKs) for Go, Python, and TypeScript (found in the `gen/` directory) to help you get started quickly.\n\nIf you plan to contribute, please review the Protobuf guidelines to ensure our API remains consistent and user-friendly.\n\n## API Endpoints\n\n* **gRPC:** `grpc.cloud.qdrant.io:443`\n* **REST/JSON:** `https://api.cloud.qdrant.io`\n\nAuthentication is typically handled via API keys (so called management keys), which are passed in the `Authorization` header as an apikey (e.g., `Authorization: apikey \u003cYOUR_MANAGEMENT_KEY\u003e`).\n\n## Authentication \u0026 Authorization\n\nThe Qdrant Cloud API implements both authentication and permission-based authorization to secure access to its methods and resources:\n\n- **Authentication**: Verifies the identity of the caller using API keys or user tokens\n- **Authorization**: Controls access to specific operations based on permissions and roles\n\nFor detailed information about authentication requirements, actor types, permissions, multiple permissions, and safe permission migration patterns, see [Authentication \u0026 Authorization Documentation](docs/auth.md).\n\n## Available Services\n\nThe Qdrant Cloud API is organized into several gRPC services, each responsible for a specific domain of functionality. Below is a list of the primary services available:\n\n| Service Name | Version | Description |\n| --- | --- | --- |\n| [AccountService](proto/qdrant/cloud/account/v1/account.proto) | **v1** | AccountService is the API used to configure Accounts. |\n| [AggregationService](proto/qdrant/cloud/ui/v1/ui.proto) | **v1** | AggregationService provides optimized methods for UI components that need aggregated data. This service combines multiple entities to reduce API round trips for common UI patterns. |\n| [AuthService](proto/qdrant/cloud/auth/v1/auth.proto) | **v1** | AuthService is the API used to manage the authentication settings (like management keys) for Qdrant Cloud. |\n| [BackupService](proto/qdrant/cloud/cluster/backup/v1/backup.proto) | **v1** | BackupService is the API used to configure backup objects. |\n| [BillingService](proto/qdrant/cloud/billing/v1/billing.proto) | **v1** | BillingService is the API used to retrieve billing information, such as invoices. |\n| [BookingService](proto/qdrant/cloud/booking/v1/booking.proto) | **v1** | BookingService is the API used to configure the booking settings (like packages objects). |\n| [ClusterDataService](proto/qdrant/cloud/ui/v1/clusterdata.proto) | **v1** | ClusterDataService provides cluster data for UI components, this is considered a beta feature. |\n| [ClusterService](proto/qdrant/cloud/cluster/v1/cluster.proto) | **v1** | ClusterService is the API used to configure cluster objects. |\n| [DatabaseApiKeyService](proto/qdrant/cloud/cluster/auth/v1/database_api_key.proto) | **v1** | Deprecated: This version of the API is deprecated. Use qdrant.cloud.cluster.auth.v2.DatabaseApiKeyService instead. DatabaseApiKeyService is the API used to manage keys that give access to a cluster database. |\n| [DatabaseApiKeyService](proto/qdrant/cloud/cluster/auth/v2/database_api_key.proto) | **v2** | DatabaseApiKeyService is the API used to manage keys that give access to a cluster database. |\n| [EphemeralDashboardTokenService](proto/qdrant/cloud/cluster/auth/v1/ephemeral_dashboard_token.proto) | **v1** | EphemeralDashboardTokenService is the API used to create ephemeral tokens to access the Qdrant Dashboard, used by the Qdrant Cloud UI |\n| [HybridCloudService](proto/qdrant/cloud/hybrid/v1/hybrid_cloud.proto) | **v1** | HybridCloudService is the API used for configuring hybrid cloud environments. |\n| [IAMService](proto/qdrant/cloud/iam/v1/iam.proto) | **v1** | IAMService is the API used to configure IAM (identity and access management) objects. |\n| [MeteringService](proto/qdrant/cloud/metering/v1/metering.proto) | **v1** | MeteringService is the API to retrieve usage data used for billing purposes. |\n| [MonitoringService](proto/qdrant/cloud/monitoring/v1/monitoring.proto) | **v1** | MonitoringService provides access to monitoring data such as cluster metrics, logs, and events. |\n| [PaymentService](proto/qdrant/cloud/payment/v1/payment.proto) | **v1** | PaymentService is the API used to manage payment settings. |\n| [PlatformService](proto/qdrant/cloud/platform/v1/platform.proto) | **v1** | PlatformService is the API used to query for cloud provider \u0026 regional information. |\n| [QuotaService](proto/qdrant/cloud/quota/v1/quota.proto) | **v1** | QuotaService is the API used to configure Quotas. |\n\n*Note: The `Service Name` links point to the respective Protocol Buffer file where that service is formally defined.\nYou can explore these files for detailed information on methods, request/response messages, and field validations.*\n\n## Interacting with the API\n\nYou can interact with the Qdrant Cloud API directly using tools like `grpcurl` (for gRPC) and `curl` (for REST/JSON), or by using the provided client libraries.\n\nThe API is used in the [TerraformProvider](https://registry.terraform.io/providers/qdrant/qdrant-cloud/latest) as well, so this can be used to interact as well.\nThe sources for the TerraformProvider can be found [in Github here](https://github.com/qdrant/terraform-provider-qdrant-cloud).\n\n### Using `grpcurl` (for gRPC)\n\n`grpcurl` is a command-line tool that lets you interact with gRPC servers. It's great for exploring and testing APIs.\n\n#### Example: List available services with `grpcurl`\n\n```sh\ngrpcurl grpc.cloud.qdrant.io:443 list\n```\n\n#### Example: Describe a service (e.g., ClusterService)\n\n```sh\ngrpcurl grpc.cloud.qdrant.io:443 describe qdrant.cloud.cluster.v1.ClusterService\n```\n\n#### Example: Call a method with gRPC (e.g., ListClusters on ClusterService)\n\n```sh\ngrpcurl -H \"Authorization: apikey \u003cYOUR_MANAGEMENT_KEY\u003e\" \\\n  -d '{\"account_id\": \"\u003cYOUR_ACCOUNT_ID\u003e\"}' \\\n  grpc.cloud.qdrant.io:443 \\\n  qdrant.cloud.cluster.v1.ClusterService/ListClusters   \n```\n\n*Note: Replace `\u003cYOUR_MANAGEMENT_KEY\u003e` with your actual management key and `\u003cYOUR_ACCOUNT_ID\u003e` with your account ID. The specific service and method names can be found in the `.proto` files under the `proto/` directory or by using `grpcurl list` and `grpcurl describe`.*\n\nAssuming you have exported your management key in the environment variable `MANAGEMENT_KEY`, you can replace the first line with:\n\n```sh\ngrpcurl -H \"Authorization: apikey ${MANAGEMENT_KEY}\" \\\n...\n``` \n\n### Using `curl` (for REST/JSON)\n\nThe REST/JSON API is available over HTTPS and uses standard HTTP methods.\n\n#### Example: Call a method with REST/JSON (e.g., Listclusters on ClusterService)\n\n```sh\ncurl -X GET \\\n  -H \"Authorization: apikey \u003cYOUR_MANAGEMENT_KEY\u003e\" \\\n  \"https://api.cloud.qdrant.io/api/cluster/v1/accounts/\u003cYOUR_ACCOUNT_ID\u003e/clusters\"\n```\n\n*Note: Replace `\u003cYOUR_MANAGEMENT_KEY\u003e` with your actual management key and `\u003cYOUR_ACCOUNT_ID\u003e` with your account ID. The exact REST path and HTTP method depend on the `google.api.http` annotations in the `.proto` files.*\n\nYou can typically infer these from the gRPC service and method names, or refer to the API documentation. Or check the output of grpcurl like:\n\n```\n  rpc CreateCluster ( .qdrant.cloud.cluster.v1.CreateClusterRequest ) returns ( .qdrant.cloud.cluster.v1.CreateClusterResponse ) {\n    option (.google.api.http) = {\n      post: \"/api/cluster/v1/accounts/{cluster.account_id}/clusters\",\n      body: \"*\"\n    };\n    option (.qdrant.cloud.common.v1.permissions) = \"write:clusters\";\n  }\n  ...\n```\n\nConsider using `| jq` to format the output.\n\n*For methods requiring a request body (e.g., POST, PUT), you would use the `-d` option with a JSON payload:*\n\n```sh\ncurl -X POST \\\n  -H \"Authorization: apikey \u003cYOUR_MANAGEMENT_KEY\u003e\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"field1\": \"value1\", \"field2\": \"value2\"}' \\\n  \"https://api.cloud.qdrant.io/v2/your-service/your-resource\"\n```\n\n### Using Generated Client Libraries (SDKs)\n\nThe `gen/` directory in this repository contains pre-generated client libraries (SDKs) to help you integrate the Qdrant Cloud API into your applications. These libraries provide type-safe methods to call the gRPC services directly.\n\nWe currently provide support for:\n* **Go:** `gen/go/`\n* **Python:** `gen/python/`\n* **TypeScript:** `gen/ts/`\n\nSee [below](#using-generated-code) for more details.\n\n\n### Paginated resources\n\nAll listing methods (e.g. `ListClusters`) currently return all active resources in a single response. To provide better usability and performance, we are gradually introducing pagination so resources can be retrieved in chunks.\n\nA `ListXXX` method supports pagination if its request message includes the fields:\n\n- `page_size` — maximum number of items per page.\n- `page_token` — token to request the next page.\n\nand the response message includes:\n\n- `items` — list of resources.\n- `total_size` — total number of matching resources.\n- `next_page_token` — token to request the next page (omit if there are no more results).\n\nThis is an example of using pagination with the `BackupService.ListBackups` method:\n\n- Request the first 20 backups:\n\n``` sh\ngrpcurl -H \"Authorization: apikey \u003cYOUR_MANAGEMENT_KEY\u003e\" \\\n  -d '{\"account_id\": \"\u003cYOUR_ACCOUNT_ID\u003e\", \"page_size\": 20}' \\\n  grpc.cloud.qdrant.io:443 \\\n  qdrant.cloud.cluster.backup.v1.BackupService/ListBackups\n```\n\n``` sh\n{\n  \"items\": [\n    {\n      \"id\": \"f7b60c5e-2f7c-450f-926d-4c43948b71a9\",\n      \"createdAt\": \"2025-05-06T07:53:10.290771Z\",\n      \"accountId\": \"\u003cREDACTED\u003e\",\n      \"clusterId\": \"a71f4794-504e-4d19-b994-32450e10e783\",\n      \"name\": \"qdrant-a71f4794-504e-4d19-b994-32450e10e783-snapshot-1746517990\",\n      \"status\": \"BACKUP_STATUS_SUCCEEDED\",\n      \"backupDuration\": \"30s\"\n    },\n    ... 19 more ...\n  ],\n  \"totalSize\": 43,\n  \"nextPageToken\": \"WyIyMDI1LTA1LTI4VDA4OjI1OjQzLjkxNDg1NyswMDowMCIsICJjYTc3Mzk3YS1jNTRjLTQ3NGQtOGEzOS0xMzZmMGZlMWI3ODUiXQ==\"\n}\n```\n\n- Request the next page, passing `page_token`:\n\n``` sh\ngrpcurl -H \"Authorization: apikey \u003cYOUR_MANAGEMENT_KEY\u003e\" \\\n  -d '{\"account_id\": \"\u003cYOUR_ACCOUNT_ID\u003e\", \"page_size\": 20, \"page_token\":\"WyIyMDI1LTA1LTI4VDA4OjI1OjQzLjkxNDg1NyswMDowMCIsICJjYTc3Mzk3YS1jNTRjLTQ3NGQtOGEzOS0xMzZmMGZlMWI3ODUiXQ==\"}' \\\n  grpc.cloud.qdrant.io:443 \\\n  qdrant.cloud.cluster.backup.v1.BackupService/ListBackups\n```\n\n``` sh\n{\n  \"items\": [\n    {\n      \"id\": \"84deb667-36a0-4d1f-a095-50f9b2a9dec4\",\n      \"createdAt\": \"2025-06-12T14:14:22.811915Z\",\n      \"accountId\": \"\u003cREDACTED\u003e\",\n      \"clusterId\": \"4d9fc7fd-1182-42fd-abce-7c8d4c3f5f32\",\n      \"name\": \"qdrant-4d9fc7fd-1182-42fd-abce-7c8d4c3f5f32-snapshot-1749737662\",\n      \"status\": \"BACKUP_STATUS_SUCCEEDED\",\n      \"backupDuration\": \"1s\"\n    },\n    ... 19 more ...\n  ],\n  \"totalSize\": 43,\n  \"nextPageToken\": \"WyIyMDI1LTA2LTI2VDE3OjQ4OjIzLjY2NjQ0MSswMDowMCIsICJhYzc1MDc4MC02N2ViLTRjZmItOTI3ZC0zYmZhZTY4OTk5OGUiXQ==\"\n}\n```\n\n## Working with Protocol Buffer definitions\n\nWe use [Buf](https://buf.build/) to lint the schemas and to generate language bindings. \n\nAdditionally, there are [these guidelines](CONTRIBUTING.md#protobuf-guidelines) to ensure our API remains consistent and user-friendly. Please follow them when contributing.\n\nThis project leverages Make to automate common tasks. To view all available commands, you can run:\n\n``` sh\nmake help\n```\n\n### Adding/updating proto files\n\nThe API schema definitions are located under the `proto/` directory. Whenever you add or modify a `.proto` file, make sure that you format and lint it accordingly. You can do that running:\n\n``` sh\nmake format\nmake lint\n```\n\n### Generating code\n\nAfter changing a `.proto` file, you should regenerate the different language bindings:\n\n``` sh\nmake generate\n```\n## Using generated code\n\n### Go projects\n\nYou can import this project and use it in your go project. Ex:\n\n``` go\nimport (\n    ...\n    qdrantauthv1 \"github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/auth/v1\"\n)\n\n```\n\n### Python projects\n\n- Make sure you are authorised to gcloud. `gcloud auth application-default login`\n\n- Install the package:\n\n    ``` sh\n    # install auth tool\n    uv tool install keyring --with keyrings.google-artifactregistry-auth --force\n    # install\n    uv add qdrant-cloud-public-api --keyring-provider subprocess  --index https://oauth2accesstoken@us-python.pkg.dev/qdrant-cloud/python/simple\n    ```\n\n\n- Now you can import the generated code in your python project. Ex:\n\n    ```python\n    from qdrant.cloud.booking.v2.booking_pb2_grpc import BookingServiceServicer\n    from qdrant.cloud.booking.v2.booking_pb2 import ListPackagesRequest\n    \n    \n    def main():\n        print(BookingServiceServicer)\n        print(ListPackagesRequest)\n    \n    \n    if __name__ == \"__main__\":\n        main()\n    ```\n\n\n### Typescript projects\n\n- Make sure you are authorised to gcloud. `gcloud auth application-default login`\n- Create `.npmrc` file in the root of your project with the following content:\n\n    ```text\n    @qdrant:registry=https://us-npm.pkg.dev/qdrant-cloud/npm/\n    //us-npm.pkg.dev/qdrant-cloud/npm/:always-auth=true\n    ```\n\n- Add auth script to your package.json file:\n\n    ```json\n      \"scripts\": {\n        ...\n        \"artifactregistry-login\": \"npx --registry=https://registry.npmjs.org google-artifactregistry-auth\"\n        ...\n      },\n    ```\n\n- Run the auth script:\n\n    ```shell\n    npm run artifactregistry-login\n    ```\n\n- Install the package:\n    ``` sh\n    npm  install @qdrant/qdrant-cloud-public-api\n    ```\n\n- Now you can import the generated code in your typescript project. Ex:\n\n  ```typescript\n  import * as grpc from '@qdrant/qdrant-cloud-public-api/qdrant/cloud/cluster/v1/cluster_pb.js';\n  import { DatabaseApiKeyService } from \"@qdrant/qdrant-cloud-public-api/qdrant/cloud/cluster/auth/v1/database_api_key_pb.js\";\n  \n  console.log('Loaded service definition keys:', Object.keys(grpc));\n  console.log(DatabaseApiKeyService);\n  ```\n\n## [Release Process](docs/release.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrant%2Fqdrant-cloud-public-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqdrant%2Fqdrant-cloud-public-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrant%2Fqdrant-cloud-public-api/lists"}