管理 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

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

指南

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

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

Open the .

¥Open the .
Navigate to your workspace.
点击左侧边栏中的“集成”。

¥Click on Integrations in the left sidebar.
点击“新建服务令牌”按钮。

¥Click on New service token button.
在弹出窗口中，在“令牌名称”字段中输入一个描述性名称。

¥In the popup, enter a descriptive name in the Token name field.
点击“创建服务令牌”按钮。

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

示例

¥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
}

响应：

¥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

`/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

`POST /databases/{databaseId}/backups/{backupId}/restore`

将备份恢复到新数据库。

¥Restore a backup to a new database.

路径参数：

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

¥Request body:
```
{
  "targetDatabaseName": "New DB Name"
}
```
响应：

¥Responses:
- 202 Accepted：已启动恢复
  
  ¥202 Accepted: Restore initiated
- 401 Unauthorized
- 409 Conflict

杂项

¥Misc

`GET /regions/postgres`

检索所有可用区域。

¥Retrieve all available regions.

响应：

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

概述​

基本 URL​

身份验证​

承载令牌​

示例​

说明​

使用服务令牌​

使用 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​

/connections/{id}​

备份​

GET /databases/{databaseId}/backups​

POST /databases/{databaseId}/backups/{backupId}/restore​

杂项​

GET /regions/postgres​

概述

基本 URL

身份验证

承载令牌

示例

说明

使用服务令牌

使用 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`

`/connections/{id}`

备份

`GET /databases/{databaseId}/backups`

`POST /databases/{databaseId}/backups/{backupId}/restore`

杂项

`GET /regions/postgres`