openapi: 3.1.0
info:
title: Prisma Client API
description: >-
Auto-generated, type-safe query builder for Node.js and TypeScript that
provides programmatic database access. Prisma Client exposes CRUD
operations (findUnique, findMany, create, update, delete, upsert),
aggregation functions (count, aggregate, groupBy), and advanced query
features including filtering, pagination, sorting, relation loading,
and transactions. This specification documents the REST-equivalent
operations that Prisma Client generates for database models, supporting
PostgreSQL, MySQL, SQLite, SQL Server, MongoDB, and CockroachDB.
version: 1.0.0
contact:
name: Prisma Support
email: [email protected]
url: https://www.prisma.io/support
license:
name: Apache-2.0
url: https://opensource.org/licenses/Apache-2.0
termsOfService: https://www.prisma.io/terms
externalDocs:
description: Prisma Client API Reference
url: https://www.prisma.io/docs/orm/reference/prisma-client-reference
servers:
- url: https://localhost:3000/api
description: >-
Local development server. Prisma Client is typically used as a library,
not a REST API. This specification documents the operations available
when exposed via a REST layer.
tags:
- name: Aggregation
description: Count, aggregate, and groupBy operations for analytics
- name: Batch
description: Batch operations for bulk create, update, and delete
- name: CRUD
description: >-
Core create, read, update, and delete operations for database models
- name: Raw
description: Raw SQL query execution
paths:
/{model}:
get:
operationId: findMany
summary: Prisma Find multiple records
description: >-
Retrieves multiple records from the specified model with optional
filtering, ordering, pagination, and relation loading. Supports
where conditions with operators (equals, contains, startsWith,
endsWith, gt, gte, lt, lte, in, notIn), orderBy on any field,
cursor-based and offset pagination via take/skip, and distinct
filtering.
tags:
- CRUD
parameters:
- $ref: '#/components/parameters/ModelName'
- name: where
in: query
description: >-
JSON-encoded filter conditions using Prisma query operators
schema:
type: string
- name: orderBy
in: query
description: >-
JSON-encoded sort specification with field names and asc/desc
schema:
type: string
- name: take
in: query
description: >-
Number of records to return. Negative values reverse the order.
schema:
type: integer
- name: skip
in: query
description: Number of records to skip for offset pagination
schema:
type: integer
minimum: 0
- name: cursor
in: query
description: >-
JSON-encoded cursor position for cursor-based pagination
schema:
type: string
- name: select
in: query
description: >-
JSON-encoded field selection specifying which properties to include
schema:
type: string
- name: include
in: query
description: >-
JSON-encoded relation loading specification for eager loading
schema:
type: string
- name: distinct
in: query
description: >-
JSON-encoded list of fields to deduplicate results by
schema:
type: string
responses:
'200':
description: Successfully retrieved records
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Record'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: create
summary: Prisma Create a new record
description: >-
Creates a new record in the specified model with the provided data.
Supports nested creation of related records via create and
connectOrCreate operations, and connecting to existing related
records via connect.
tags:
- CRUD
parameters:
- $ref: '#/components/parameters/ModelName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInput'
responses:
'201':
description: Successfully created record
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
'400':
$ref: '#/components/responses/BadRequest'
'409':
description: Unique constraint violation
content:
application/json:
schema:
$ref: '#/components/schemas/PrismaError'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/{id}:
get:
operationId: findUnique
summary: Prisma Find a unique record
description: >-
Retrieves a single record by its unique identifier or compound unique
constraint. Returns null if no record matches. Use select to specify
which fields to return and include for eager-loading relations.
tags:
- CRUD
parameters:
- $ref: '#/components/parameters/ModelName'
- $ref: '#/components/parameters/RecordId'
- name: select
in: query
description: JSON-encoded field selection
schema:
type: string
- name: include
in: query
description: JSON-encoded relation loading specification
schema:
type: string
responses:
'200':
description: Successfully retrieved record
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
put:
operationId: update
summary: Prisma Update a record
description: >-
Updates an existing record identified by its unique identifier. Supports
atomic number operations (increment, decrement, multiply, divide),
nested relation updates (create, connect, disconnect, delete, update,
upsert, set), and conditional updates.
tags:
- CRUD
parameters:
- $ref: '#/components/parameters/ModelName'
- $ref: '#/components/parameters/RecordId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateInput'
responses:
'200':
description: Successfully updated record
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: Unique constraint violation
content:
application/json:
schema:
$ref: '#/components/schemas/PrismaError'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
operationId: deleteRecord
summary: Prisma Delete a record
description: >-
Permanently deletes a single record identified by its unique
identifier. Returns the deleted record data. Cascading deletes
may apply based on the Prisma schema relation configuration.
tags:
- CRUD
parameters:
- $ref: '#/components/parameters/ModelName'
- $ref: '#/components/parameters/RecordId'
responses:
'200':
description: Successfully deleted record, returns the deleted data
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/upsert:
post:
operationId: upsert
summary: Prisma Upsert a record
description: >-
Updates a record if it exists matching the where condition, or creates
a new record if no match is found. Requires both create and update
data to be provided along with the where condition.
tags:
- CRUD
parameters:
- $ref: '#/components/parameters/ModelName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertInput'
responses:
'200':
description: Successfully upserted record
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/first:
get:
operationId: findFirst
summary: Prisma Find the first matching record
description: >-
Returns the first record that matches the filter criteria. Supports
the same filtering and ordering options as findMany. Returns null
if no records match.
tags:
- CRUD
parameters:
- $ref: '#/components/parameters/ModelName'
- name: where
in: query
description: JSON-encoded filter conditions
schema:
type: string
- name: orderBy
in: query
description: JSON-encoded sort specification
schema:
type: string
- name: select
in: query
description: JSON-encoded field selection
schema:
type: string
- name: include
in: query
description: JSON-encoded relation loading specification
schema:
type: string
responses:
'200':
description: Successfully retrieved the first matching record
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
'404':
description: No matching record found
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/count:
get:
operationId: count
summary: Prisma Count matching records
description: >-
Returns the count of records matching the filter criteria. Optionally
provides field-level counts showing how many non-null values exist
for each specified field.
tags:
- Aggregation
parameters:
- $ref: '#/components/parameters/ModelName'
- name: where
in: query
description: JSON-encoded filter conditions
schema:
type: string
- name: select
in: query
description: JSON-encoded field selection for field-level counts
schema:
type: string
responses:
'200':
description: Successfully retrieved count
content:
application/json:
schema:
oneOf:
- type: integer
description: Total count when no field selection
- type: object
description: Field-level counts
additionalProperties:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/aggregate:
get:
operationId: aggregate
summary: Prisma Aggregate records
description: >-
Performs aggregate calculations on matching records. Supports _count,
_avg, _sum, _min, and _max operations on numeric fields with optional
filtering and ordering.
tags:
- Aggregation
parameters:
- $ref: '#/components/parameters/ModelName'
- name: where
in: query
description: JSON-encoded filter conditions
schema:
type: string
- name: _count
in: query
description: Fields to count or true for total count
schema:
type: string
- name: _avg
in: query
description: JSON-encoded specification of fields to average
schema:
type: string
- name: _sum
in: query
description: JSON-encoded specification of fields to sum
schema:
type: string
- name: _min
in: query
description: JSON-encoded specification of fields to find minimum
schema:
type: string
- name: _max
in: query
description: JSON-encoded specification of fields to find maximum
schema:
type: string
responses:
'200':
description: Successfully performed aggregation
content:
application/json:
schema:
$ref: '#/components/schemas/AggregateResult'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/groupBy:
get:
operationId: groupBy
summary: Prisma Group records and aggregate
description: >-
Groups records by one or more fields and applies aggregate functions
within each group. Supports filtering groups with having conditions
and ordering groups by field values or aggregate results.
tags:
- Aggregation
parameters:
- $ref: '#/components/parameters/ModelName'
- name: by
in: query
required: true
description: JSON-encoded list of fields to group by
schema:
type: string
- name: where
in: query
description: JSON-encoded filter conditions applied before grouping
schema:
type: string
- name: having
in: query
description: JSON-encoded filter conditions applied after grouping
schema:
type: string
- name: orderBy
in: query
description: JSON-encoded sort specification for groups
schema:
type: string
responses:
'200':
description: Successfully grouped and aggregated records
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GroupByResult'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/createMany:
post:
operationId: createMany
summary: Prisma Create multiple records
description: >-
Inserts multiple records in a single transaction. Optionally skips
records that would violate unique constraints. Returns a count of
created records. On PostgreSQL, CockroachDB, and SQLite, use
createManyAndReturn to also retrieve the created records.
tags:
- Batch
parameters:
- $ref: '#/components/parameters/ModelName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateManyInput'
responses:
'200':
description: Successfully created records
content:
application/json:
schema:
$ref: '#/components/schemas/BatchPayload'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/updateMany:
patch:
operationId: updateMany
summary: Prisma Update multiple records
description: >-
Updates all records matching the filter criteria with the provided
data. Returns a count of the number of records updated. Does not
return the updated records themselves.
tags:
- Batch
parameters:
- $ref: '#/components/parameters/ModelName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateManyInput'
responses:
'200':
description: Successfully updated records
content:
application/json:
schema:
$ref: '#/components/schemas/BatchPayload'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/{model}/deleteMany:
delete:
operationId: deleteMany
summary: Prisma Delete multiple records
description: >-
Deletes all records matching the filter criteria. Returns a count of
the number of records deleted. If no filter is provided, all records
in the model are deleted.
tags:
- Batch
parameters:
- $ref: '#/components/parameters/ModelName'
- name: where
in: query
description: JSON-encoded filter conditions
schema:
type: string
responses:
'200':
description: Successfully deleted records
content:
application/json:
schema:
$ref: '#/components/schemas/BatchPayload'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/raw/query:
post:
operationId: queryRaw
summary: Prisma Execute a raw SQL query
description: >-
Executes a raw SQL SELECT query against the database and returns the
result set. Use parameterized queries to prevent SQL injection.
tags:
- Raw
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RawQueryInput'
responses:
'200':
description: Successfully executed query
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/raw/execute:
post:
operationId: executeRaw
summary: Prisma Execute a raw SQL statement
description: >-
Executes a raw SQL statement (INSERT, UPDATE, DELETE, DDL) against
the database and returns the number of affected rows.
tags:
- Raw
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RawQueryInput'
responses:
'200':
description: Successfully executed statement
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: Number of rows affected
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
components:
parameters:
ModelName:
name: model
in: path
required: true
description: >-
The Prisma model name (e.g., user, post, comment) as defined in the
Prisma schema file
schema:
type: string
examples:
- user
- post
RecordId:
name: id
in: path
required: true
description: Unique identifier of the record
schema:
type: string
schemas:
Record:
type: object
description: >-
A database record. The structure depends on the model schema and
select/include options used in the query.
additionalProperties: true
CreateInput:
type: object
description: Input data for creating a new record
properties:
data:
type: object
description: The field values for the new record
additionalProperties: true
select:
type: object
description: Fields to include in the returned record
additionalProperties:
type: boolean
include:
type: object
description: Relations to eagerly load in the returned record
additionalProperties:
type: boolean
required:
- data
UpdateInput:
type: object
description: Input data for updating a record
properties:
data:
type: object
description: The field values to update
additionalProperties: true
select:
type: object
description: Fields to include in the returned record
additionalProperties:
type: boolean
include:
type: object
description: Relations to eagerly load in the returned record
additionalProperties:
type: boolean
required:
- data
UpsertInput:
type: object
description: Input data for upserting a record
properties:
where:
type: object
description: Unique identifier to search for an existing record
additionalProperties: true
create:
type: object
description: Data to use if creating a new record
additionalProperties: true
update:
type: object
description: Data to use if updating an existing record
additionalProperties: true
select:
type: object
description: Fields to include in the returned record
additionalProperties:
type: boolean
include:
type: object
description: Relations to eagerly load in the returned record
additionalProperties:
type: boolean
required:
- where
- create
- update
CreateManyInput:
type: object
description: Input data for creating multiple records
properties:
data:
type: array
description: Array of records to create
items:
type: object
additionalProperties: true
skipDuplicates:
type: boolean
description: Skip records that violate unique constraints
default: false
required:
- data
UpdateManyInput:
type: object
description: Input data for updating multiple records
properties:
where:
type: object
description: Filter conditions to select records to update
additionalProperties: true
data:
type: object
description: Field values to update
additionalProperties: true
required:
- data
RawQueryInput:
type: object
description: Input for raw SQL query execution
properties:
query:
type: string
description: The SQL query string with $1, $2 parameter placeholders
examples:
- SELECT * FROM "User" WHERE email = $1
parameters:
type: array
description: Parameter values for the query placeholders
items: {}
required:
- query
BatchPayload:
type: object
description: Result of a batch operation with the count of affected records
properties:
count:
type: integer
description: Number of records affected by the operation
minimum: 0
required:
- count
AggregateResult:
type: object
description: Result of an aggregation operation
properties:
_count:
type: object
description: Count of records or field-level counts
additionalProperties:
type: integer
_avg:
type: object
description: Average values for numeric fields
additionalProperties:
type: number
_sum:
type: object
description: Sum of numeric field values
additionalProperties:
type: number
_min:
type: object
description: Minimum values per field
additionalProperties: true
_max:
type: object
description: Maximum values per field
additionalProperties: true
GroupByResult:
type: object
description: A single group result from a groupBy operation
additionalProperties: true
PrismaError:
type: object
description: >-
Error response from Prisma Client. Error codes follow the Pxxxx format
documented at https://www.prisma.io/docs/orm/reference/error-reference
properties:
code:
type: string
description: Prisma error code (e.g., P2002 for unique constraint violation)
pattern: '^P[0-9]{4}$'
examples:
- P2002
- P2025
message:
type: string
description: Human-readable error description
meta:
type: object
description: Additional error context
additionalProperties: true
required:
- code
- message
responses:
BadRequest:
description: The request was invalid or malformed
content:
application/json:
schema:
$ref: '#/components/schemas/PrismaError'
NotFound:
description: The requested record was not found
content:
application/json:
schema:
$ref: '#/components/schemas/PrismaError'
InternalServerError:
description: An unexpected error occurred
content:
application/json:
schema:
$ref: '#/components/schemas/PrismaError'