Skip to main content

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

The API reference is also available via an OpenAPI 3.1. spec.

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}/databases/{databaseId}

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

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.

  • 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
  • Responses:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

POST /projects/{projectId}/databases​

Create a new database.

  • Request body: 
    {
      "region": "us-east-1",
      "name": "My Database",
      "isDefault": false
    }
  • Responses:
    • 201 Created
    • 400 Default database already exists
    • 401 Unauthorized
    • 403 Forbidden

GET /projects/{projectId}/databases/{databaseId}​

Retrieve a specific database.

  • Responses:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /projects/{projectId}/databases/{databaseId}​

Delete a database.

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

Connection strings​

GET /projects/{projectId}/databases/{databaseId}/connections​

Retrieve all database connection strings.

  • Query parameters:
    • cursor
    • limit
  • Responses:
    • 200 OK
    • 401 Unauthorized

POST /projects/{projectId}/databases/{databaseId}/connections​

Create a new connection string.

  • Request body:

    {
      "name": "Connection Name"
    }

  • Responses:

    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /projects/{projectId}/databases/{databaseId}/connections/{id}​

Delete a connection string.

  • Responses:
    • 204 No Content
    • 401 Unauthorized
    • 404 Not Found

Backups​

GET /projects/{projectId}/databases/{databaseId}/backups​

Retrieve database backups.

  • Responses:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

POST /projects/{projectId}/databases/{databaseId}/backups/{backupId}/recoveries​

Restore a backup to a new database.

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

Misc​

GET /regions​

Retrieve all available regions.

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