Management API

Overview

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.

Guides

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

• Getting started with the Prisma Management API
• Provisioning preview databases with GitHub Actions and Prisma Postgres
• Partner database provisioning & user claim flow

Base URL

The base URL for a Prisma Postgres API request is:

https://api.prisma.io/v1

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

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

• Service tokens (manually created in your workspace)
• OAuth 2 access tokens

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:

1. Open the .
2. Navigate to your workspace.
3. Navigate to the Settings page of your workspace and select Service Tokens.
4. Click New Service Token.
5. 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

1. Create a new request.
2. Go to the Authorization tab.
3. Set type to Bearer Token.
4. Paste your service token.

Using OAuth 2

1. In the Authorization tab, set type to OAuth 2.0.
2. Click Get New Access Token and fill in the details:
   • Token Name: Any name
   • Grant Type: Authorization Code
   • Callback URL: http://localhost:8789/swagger/oauth2-redirect.html
   • Auth URL / Access Token URL: Your local OAuth URLs
   • Client ID / Secret: From the script output
   • Scope: (as needed)
3. After completing the flow, use the token in your requests.

Authentication in SwaggerUI

Using a Service token

1. Click Authorize.
2. Paste the service token into the relevant input.
3. Click Authorize again.

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

Using OAuth 2

1. Click Authorize.
2. Choose the OAuth2 flow.
3. Provide your clientId, clientSecret, and redirect URI.
4. Complete the authorization flow to acquire access.

Endpoints

Workspaces

GET /workspaces

Retrieve information about the workspaces accessible by the current user.

• Query parameters:
  • cursor (optional): Cursor for pagination
  • limit (optional, default: 100): Limit number of results
• Responses:
  • 200 OK: List of workspaces
  • 401 Unauthorized: Invalid or missing authentication token

Projects

GET /projects

Retrieve all projects.

• Query parameters:
  • cursor (optional): Cursor for pagination
  • limit (optional, default: 100): Limit number of results
• Responses:
  • 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: Project created
  • 401 Unauthorized

GET /projects/{id}

Retrieve a specific project by ID.

• Path parameters:
  • id: Project ID
• Responses:
  • 200 OK
  • 401 Unauthorized
  • 404 Not Found

DELETE /projects/{id}

Deletes a project.

• Path parameters:
  • id: Project ID
• Responses:
  • 204 No Content
  • 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: 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: Project ID
• Query parameters:
  • cursor (optional): Cursor for pagination
  • 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: 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: Database ID
• Responses:
  • 200 OK
  • 401 Unauthorized
  • 404 Not Found

DELETE /databases/{databaseId}

Delete a database.

• Path parameters:
  • 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: Database ID
• Query parameters:
  • cursor (optional): Cursor for pagination
  • 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: Database ID

• Request body:

  {
    "name": "Connection Name"
  }

• Responses:

  • 200 OK
  • 401 Unauthorized
  • 404 Not Found

/connections/{id}

Delete a connection string.

• Path parameters:
  • id: Connection ID
• Responses:
  • 204 No Content
  • 401 Unauthorized
  • 404 Not Found

Backups

GET /databases/{databaseId}/backups

Retrieve database backups.

• Path parameters:
  • databaseId: Database ID
• Query parameters:
  • 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: Database ID
  • backupId: Database backup ID
• Request body:

  {
    "targetDatabaseName": "New DB Name"
  }
• Responses:
  • 202 Accepted: Restore initiated
  • 401 Unauthorized
  • 409 Conflict

Misc

GET /regions/postgres

Retrieve all available regions.

• Responses:
  • 200 OK: Returns list of available/unsupported regions
  • 401 Unauthorized