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: support@prisma.io
    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'