管理 API

概述

¥Overview

本页介绍 Prisma Management API，它使你能够以编程方式在中管理 platform 资源（例如项目或 Prisma Postgres 实例）。

¥This page covers the Prisma Management API which enables you to programmatically manage platform resources (e.g. projects or Prisma Postgres instances) in .

OpenAPI

交互式 OpenAPI 3.1 规范可在此处获取，你可以在其中探索端点、请求/响应主体以及详细示例。

¥An interactive OpenAPI 3.1 specification is available here, where you can explore endpoints, request/response bodies, and detailed examples.

指南

我们有三个指南可帮助你在常见场景中使用 Management API：

¥We have three guides to help you use the Management API for common scenarios:

基本 URL

¥Base URL

Prisma Postgres API 请求的基本 URL 为：

¥The base URL for a Prisma Postgres API request is:

https://api.prisma.io/v1

将端点路径附加到基本 URL 以构建请求的完整 URL。例如：

¥Append an endpoint path to the base URL to construct the full URL for a request. For example:

https://api.prisma.io/v1/projects/{projectId}

身份验证

¥Authentication

承载令牌

¥Bearer tokens

Prisma Postgres API 使用 Bearer Token 身份验证，并支持两种类型的令牌：

¥The Prisma Postgres API uses Bearer Token Authentication and supports two kinds of tokens:

服务令牌（在你的工作区中手动创建）

¥Service tokens (manually created in your workspace)
OAuth 2 访问令牌

¥OAuth 2 access tokens

要遵守 Bearer Token 身份验证，你需要按如下方式格式化你的 Authorization 标头：

¥To adhere to the Bearer Token Authentication, you need to format your Authorization header like this:

Authorization: Bearer $TOKEN

创建服务令牌

¥Creating a service token

你可以像这样创建服务令牌来使用管理 API：

¥You can create a service token to use the Management API like this:

打开。

¥Open the .
导航到你的工作区。

¥Navigate to your workspace.
导航到工作区的“设置”页面，然后选择“服务令牌”。

¥Navigate to the Settings page of your workspace and select Service Tokens.
点击“新建服务令牌”。

¥Click New Service Token.
复制生成的令牌并将其存储在安全的位置以备将来使用。

¥Copy the generated token and store it in a safe location for future use.

创建 OAuth 凭据

¥Creating OAuth credentials

要获取客户端 ID 和客户端密钥，请执行以下流程：

¥To obtain a client ID and client secret, go through this flow:

打开。

¥Open the .
点击侧边栏中的 🧩 Integrations 选项卡。

¥Click the 🧩 Integrations tab in the sidenav.
在“已发布的应用”部分中，单击“新建应用”按钮以开始创建新的 OAuth 应用。

¥In the Published Applications section, click the New Application button to start creating a new OAuth app.
为你的 OAuth 应用输入名称、描述和回调 URL。

¥Enter a Name, Description, and Callback URL for your OAuth app.
点击“继续”。

¥Click Continue.

在下一个屏幕上，复制并存储 OAuth 应用的客户端 ID 和客户端密钥到安全的位置。

¥On the next screen, copy and store the client ID and client secret for your OAuth app in a secure location.

示例

¥Example

curl --location "https://api.prisma.io/v1/projects" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data \
  "{ 
    \"name\": \"my_project\", 
    \"region\": \"us-east-1\" 
  }"

说明

¥Instructions

Authentication in Postman

使用服务令牌

¥Using a Service token

创建新请求。

¥Create a new request.
转到“授权”选项卡。

¥Go to the Authorization tab.
将类型设置为 Bearer Token。

¥Set type to Bearer Token.
粘贴你的服务令牌。

¥Paste your service token.

使用 OAuth 2

¥Using OAuth 2

在“授权”选项卡中，将类型设置为 OAuth 2.0。

¥In the Authorization tab, set type to OAuth 2.0.
点击“获取新的访问令牌”并填写详细信息：

¥Click Get New Access Token and fill in the details:
- 令牌名称：任意名称
  
  ¥Token Name: Any name
- 授权类型：授权码
  
  ¥Grant Type: Authorization Code
- 回调 URL：http://localhost:8789/swagger/oauth2-redirect.html
  
  ¥Callback URL: http://localhost:8789/swagger/oauth2-redirect.html
- 授权 URL / 访问令牌 URL：你的本地 OAuth URL
  
  ¥Auth URL / Access Token URL: Your local OAuth URLs
- 客户端 ID/密钥：来自脚本输出
  
  ¥Client ID / Secret: From the script output
- 范围：（根据需要）
  
  ¥Scope: (as needed)
完成流程后，请在请求中使用令牌。

¥After completing the flow, use the token in your requests.

Authentication in SwaggerUI

使用服务令牌

¥Using a Service token

点击“授权”。

¥Click Authorize.
将服务令牌粘贴到相关输入中。

¥Paste the service token into the relevant input.
再次点击“授权”。

¥Click Authorize again.

Swagger 规范通过 Authorization 标头支持 Bearer 令牌。

¥The Swagger spec supports a Bearer token via the Authorization header.

使用 OAuth 2

¥Using OAuth 2

点击“授权”。

¥Click Authorize.
选择 OAuth2 流程。

¥Choose the OAuth2 flow.
请提供你的 clientId、clientSecret 和重定向 URI。

¥Provide your clientId, clientSecret, and redirect URI.
完成授权流程以获取访问权限。

¥Complete the authorization flow to acquire access.

端点

¥Endpoints

工作区

¥Workspaces

`GET /workspaces`

检索当前用户可访问的工作区信息。

¥Retrieve information about the workspaces accessible by the current user.

查询参数：

¥Query parameters:
- cursor（可选）：分页光标
  
  ¥cursor (optional): Cursor for pagination
- limit（可选，默认值：100）：结果数量限制
  
  ¥limit (optional, default: 100): Limit number of results
响应：

¥Responses:
- 200 OK：工作区列表
  
  ¥200 OK: List of workspaces
- 401 Unauthorized：身份验证令牌无效或缺失
  
  ¥401 Unauthorized: Invalid or missing authentication token

项目

¥Projects

`GET /projects`

检索所有项目。

¥Retrieve all projects.

查询参数：

¥Query parameters:
- cursor（可选）：分页光标
  
  ¥cursor (optional): Cursor for pagination
- limit（可选，默认值：100）：结果数量限制
  
  ¥limit (optional, default: 100): Limit number of results
响应：

¥Responses:
- 200 OK：项目列表
  
  ¥200 OK: List of projects
- 401 Unauthorized

`POST /projects`

创建新项目。

¥Create a new project.

请求正文：

¥Request body:

{
  "region": "us-east-1",
  "name": "My Project"
}

响应：

¥Responses:
- 201 Created：项目已创建
  
  ¥201 Created: Project created
- 401 Unauthorized

`GET /projects/{id}`

通过 ID 检索特定项目。

¥Retrieve a specific project by ID.

路径参数：

¥Path parameters:
- id：项目 ID
  
  ¥id: Project ID
响应：

¥Responses:
- 200 OK
- 401 Unauthorized
- 404 Not Found

`DELETE /projects/{id}`

删除项目。

¥Deletes a project.

路径参数：

¥Path parameters:
- id：项目 ID
  
  ¥id: Project ID
响应：

¥Responses:
- 204 No Content
- 400 Bad Request：依赖阻止删除
  
  ¥400 Bad Request: Dependencies prevent deletion
- 401 Unauthorized
- 404 Not Found

`POST /projects/{id}/transfer`

将项目转移给新的工作区所有者。

¥Transfer a project to a new workspace owner.

路径参数：

¥Path parameters:
- id：项目 ID
  
  ¥id: Project ID
请求正文：

¥Request body:
```
{
  "recipientAccessToken": "string"
}
```
响应：

¥Responses:
- 200 OK
- 401 Unauthorized
- 404 Not Found

数据库

¥Databases

`GET /projects/{projectId}/databases`

检索项目的所有数据库。

¥Retrieve all databases for a project.

路径参数：

¥Path parameters:
- projectId：项目 ID
  
  ¥projectId: Project ID
查询参数：

¥Query parameters:
- cursor（可选）：分页光标
  
  ¥cursor (optional): Cursor for pagination
- limit（可选，默认值：100）：结果数量限制
  
  ¥limit (optional, default: 100): Limit number of results
响应：

¥Responses:
- 200 OK
- 401 Unauthorized
- 404 Not Found

`POST /projects/{projectId}/databases`

创建新数据库。

¥Create a new database.

路径参数：

¥Path parameters:
- projectId：项目 ID
  
  ¥projectId: Project ID

请求正文：

¥Request body:

{
  "region": "us-east-1",
  "name": "My Database",
  "isDefault": false,
  "fromDatabase": { 
    "id": "databaseId", 
    "backupId": "string"
  }
}

note

fromDatabase only when creating the database from an existing one or a backup. :::使用

响应：

¥Responses:
- 201 Created
- 400 Default database already exists
- 401 Unauthorized
- 403 Forbidden

`GET /databases/{databaseId}`

检索特定数据库。

¥Retrieve a specific database.

路径参数：

¥Path parameters:
- databaseId：数据库 ID
  
  ¥databaseId: Database ID
响应：

¥Responses:
- 200 OK
- 401 Unauthorized
- 404 Not Found

`DELETE /databases/{databaseId}`

删除数据库。

¥Delete a database.

路径参数：

¥Path parameters:
- databaseId：数据库 ID
  
  ¥databaseId: Database ID
响应：

¥Responses:
- 200 OK
- 401 Unauthorized
- 403 Cannot delete default environment
- 404 Not Found

连接字符串

¥Connection strings

`GET /databases/{databaseId}/connections`

检索所有数据库连接字符串。

¥Retrieve all database connection strings.

路径参数：

¥Path parameters:
- databaseId：数据库 ID
  
  ¥databaseId: Database ID
查询参数：

¥Query parameters:
- cursor（可选）：分页光标
  
  ¥cursor (optional): Cursor for pagination
- limit（可选，默认值：100）：结果数量限制
  
  ¥limit (optional, default: 100): Limit number of results
响应：

¥Responses:
- 200 OK
- 401 Unauthorized

`POST /databases/{databaseId}/connections`

创建一个新的连接字符串。

¥Create a new connection string.

路径参数：

¥Path parameters:
- databaseId：数据库 ID
  
  ¥databaseId: Database ID
请求正文：

¥Request body:
```
{
  "name": "Connection Name"
}
```
响应：

¥Responses:
- 200 OK
- 401 Unauthorized
- 404 Not Found

`DELETE /connections/{id}`

删除连接字符串。

¥Delete a connection string.

路径参数：

¥Path parameters:
- id：连接 ID
  
  ¥id: Connection ID
响应：

¥Responses:
- 204 No Content
- 401 Unauthorized
- 404 Not Found

备份

¥Backups

`GET /databases/{databaseId}/backups`

检索数据库备份。

¥Retrieve database backups.

路径参数：

¥Path parameters:
- databaseId：数据库 ID
  
  ¥databaseId: Database ID
查询参数：

¥Query parameters:
- limit（可选，默认值：25）：结果数量限制
  
  ¥limit (optional, default: 25): Limit number of results
响应：

¥Responses:
- 200 OK
- 401 Unauthorized
- 404 Not Found

集成

¥Integrations

`GET /workspaces/{workspaceId}/integrations`

检索给定工作区的集成。

¥Retrieve integrations for the given workspace.

路径参数：

¥Path parameters:
- workspaceId：工作区 ID
  
  ¥workspaceId: Workspace ID
查询参数：

¥Query parameters:
- cursor（可选）：分页光标
  
  ¥cursor (optional): Cursor for pagination
- limit（可选，默认值：100）：结果数量限制
  
  ¥limit (optional, default: 100): Limit number of results
响应：

¥Responses:
- 200 OK：集成详情列表：
  
  ¥200 OK: List of integrations with details:
  - id：集成 ID
    
    ¥id: Integration ID
  - createdAt：创建时间戳
    
    ¥createdAt: Creation timestamp
  - scopes：授权范围数组
    
    ¥scopes: Array of granted scopes
  - client：包含 id、name、createdAt 的对象
    
    ¥client: Object containing id, name, createdAt
  - createdByUser：包含 id、email、displayName 的对象
    
    ¥createdByUser: Object containing id, email, displayName
- 401 Unauthorized：缺少或无效的身份验证令牌
  
  ¥401 Unauthorized: Missing or invalid authentication token
- 404 Not Found：未找到工作区
  
  ¥404 Not Found: Workspace not found

`DELETE /workspaces/{workspaceId}/integrations/{clientId}`

撤销指定客户端 ID 的集成令牌。

¥Revokes the integration tokens with the given client ID.

路径参数：

¥Path parameters:
- workspaceId：工作区 ID（例如 wksp_1234）
  
  ¥workspaceId: Workspace ID (e.g. wksp_1234)
- clientId：集成客户端 ID（例如 itgr_5678）
  
  ¥clientId: Integration client ID (e.g. itgr_5678)
响应：

¥Responses:
- 204 No Content：集成令牌已成功撤销
  
  ¥204 No Content: Integration tokens revoked successfully
- 401 Unauthorized：缺少或无效的身份验证令牌
  
  ¥401 Unauthorized: Missing or invalid authentication token
- 404 Not Found：未找到工作区或集成
  
  ¥404 Not Found: Workspace or integration not found

杂项

¥Misc

`GET /regions/postgres`

检索所有可用区域。

¥Retrieve all available regions.

响应：

¥Responses:
- 200 OK：返回可用/不支持的区域列表
  
  ¥200 OK: Returns list of available/unsupported regions
- 401 Unauthorized

概述​

基本 URL​

身份验证​

承载令牌​

创建服务令牌​

创建 OAuth 凭据​

示例​

说明​

使用服务令牌​

使用 OAuth 2​

使用服务令牌​

使用 OAuth 2​

端点​

工作区​

GET /workspaces​

项目​

GET /projects​

POST /projects​

GET /projects/{id}​

DELETE /projects/{id}​

POST /projects/{id}/transfer​

数据库​

GET /projects/{projectId}/databases​

POST /projects/{projectId}/databases​

GET /databases/{databaseId}​

DELETE /databases/{databaseId}​

连接字符串​

GET /databases/{databaseId}/connections​

POST /databases/{databaseId}/connections​

DELETE /connections/{id}​

备份​

GET /databases/{databaseId}/backups​

集成​

GET /workspaces/{workspaceId}/integrations​

DELETE /workspaces/{workspaceId}/integrations/{clientId}​

杂项​

GET /regions/postgres​

概述

基本 URL

身份验证

承载令牌

创建服务令牌

创建 OAuth 凭据

示例

说明

使用服务令牌

使用 OAuth 2

使用服务令牌

使用 OAuth 2

端点

工作区

`GET /workspaces`

项目

`GET /projects`

`POST /projects`

`GET /projects/{id}`

`DELETE /projects/{id}`

`POST /projects/{id}/transfer`

数据库

`GET /projects/{projectId}/databases`

`POST /projects/{projectId}/databases`

`GET /databases/{databaseId}`

`DELETE /databases/{databaseId}`

连接字符串

`GET /databases/{databaseId}/connections`

`POST /databases/{databaseId}/connections`

`DELETE /connections/{id}`

备份

`GET /databases/{databaseId}/backups`

集成

`GET /workspaces/{workspaceId}/integrations`

`DELETE /workspaces/{workspaceId}/integrations/{clientId}`

杂项

`GET /regions/postgres`