Prisma Optimize API

openapi: 3.1.0
info:
  title: Prisma Optimize API
  description: >-
    API for Prisma Optimize, a query performance analysis tool for debugging
    and improving database queries during development. Optimize captures query
    execution data from Prisma Client via the @prisma/extension-optimize
    extension, analyzes query patterns, and provides AI-powered recommendations
    to reduce database load and improve application responsiveness. The service
    records queries during development sessions and provides performance
    insights through the Prisma Data Platform Console. Supports PostgreSQL,
    MySQL/MariaDB, CockroachDB, and MS SQL Server.
  version: 1.0.0
  contact:
    name: Prisma Support
    email: support@prisma.io
    url: https://www.prisma.io/support
  license:
    name: Proprietary
    url: https://www.prisma.io/terms
  termsOfService: https://www.prisma.io/terms
externalDocs:
  description: Prisma Optimize Documentation
  url: https://www.prisma.io/docs/optimize
servers:
  - url: https://optimize.prisma-data.net
    description: Prisma Optimize production endpoint
security:
  - apiKeyAuth: []
tags:
  - name: Metrics
    description: Performance metrics and statistics
  - name: Queries
    description: Recorded query retrieval and analysis
  - name: Recommendations
    description: AI-powered query optimization recommendations
  - name: Sessions
    description: Recording session management for query capture and analysis
paths:
  /sessions:
    post:
      operationId: createSession
      summary: Prisma Create a recording session
      description: >-
        Creates a new query recording session. The Optimize extension captures
        all Prisma Client queries executed during an active session and sends
        them to the Optimize service for analysis. Sessions are intended for
        use in local development environments only.
      tags:
        - Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreate'
      responses:
        '201':
          description: Recording session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: listSessions
      summary: Prisma List recording sessions
      description: >-
        Retrieves a list of all recording sessions for the current environment,
        including their status, duration, and query counts.
      tags:
        - Sessions
      parameters:
        - name: status
          in: query
          description: Filter sessions by status
          schema:
            type: string
            enum:
              - active
              - completed
              - expired
        - name: limit
          in: query
          description: Maximum number of sessions to return
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: offset
          in: query
          description: Number of sessions to skip for pagination
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successfully retrieved list of sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Session'
                  total:
                    type: integer
                    description: Total number of sessions
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sessions/{sessionId}:
    get:
      operationId: getSession
      summary: Prisma Get a recording session
      description: >-
        Retrieves detailed information about a specific recording session
        including query statistics and analysis status.
      tags:
        - Sessions
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Successfully retrieved session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: stopSession
      summary: Prisma Stop a recording session
      description: >-
        Stops an active recording session and finalizes the captured query
        data for analysis. Once stopped, no new queries will be captured
        for this session.
      tags:
        - Sessions
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Session stopped successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sessions/{sessionId}/queries:
    get:
      operationId: listSessionQueries
      summary: Prisma List queries from a session
      description: >-
        Retrieves all queries captured during a specific recording session.
        Queries include the operation type, execution time, affected model,
        and generated SQL.
      tags:
        - Queries
      parameters:
        - $ref: '#/components/parameters/SessionId'
        - name: orderBy
          in: query
          description: Sort queries by the specified field
          schema:
            type: string
            enum:
              - duration
              - timestamp
              - model
            default: timestamp
        - name: order
          in: query
          description: Sort direction
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Successfully retrieved session queries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecordedQuery'
                  total:
                    type: integer
                    description: Total number of queries in the session
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sessions/{sessionId}/queries/{queryId}:
    get:
      operationId: getQueryDetails
      summary: Prisma Get query details
      description: >-
        Retrieves detailed information about a specific recorded query
        including the full SQL, execution plan, and performance metrics.
      tags:
        - Queries
      parameters:
        - $ref: '#/components/parameters/SessionId'
        - name: queryId
          in: path
          required: true
          description: Unique identifier of the recorded query
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved query details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordedQuery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sessions/{sessionId}/recommendations:
    get:
      operationId: listRecommendations
      summary: Prisma List optimization recommendations
      description: >-
        Retrieves AI-powered optimization recommendations for queries
        captured in the session. Recommendations include suggestions for
        adding indexes, restructuring queries, implementing caching
        strategies, and using Prisma features like select and include more
        efficiently.
      tags:
        - Recommendations
      parameters:
        - $ref: '#/components/parameters/SessionId'
        - name: severity
          in: query
          description: Filter recommendations by severity level
          schema:
            type: string
            enum:
              - critical
              - warning
              - info
      responses:
        '200':
          description: Successfully retrieved recommendations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Recommendation'
                  total:
                    type: integer
                    description: Total number of recommendations
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sessions/{sessionId}/metrics:
    get:
      operationId: getSessionMetrics
      summary: Prisma Get session performance metrics
      description: >-
        Retrieves aggregated performance metrics for all queries in a session
        including total execution time, average query duration, slowest
        queries, and query type distribution.
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Successfully retrieved session metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionMetrics'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /ingest:
    post:
      operationId: ingestQueryData
      summary: Prisma Ingest query execution data
      description: >-
        Receives query execution data from the Prisma Optimize extension
        running in development. This endpoint is called automatically by
        the extension and is not typically invoked directly.
      tags:
        - Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryIngestPayload'
      responses:
        '202':
          description: Query data accepted for processing
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Optimize API key generated from the Prisma Data Platform Console.
        Passed via the OPTIMIZE_API_KEY environment variable to the extension.
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      description: Unique identifier of the recording session
      schema:
        type: string
  schemas:
    SessionCreate:
      type: object
      description: Request body for creating a new recording session
      properties:
        name:
          type: string
          description: Optional display name for the session
          examples:
            - Feature development session
        databaseProvider:
          type: string
          description: The database provider being used
          enum:
            - postgresql
            - mysql
            - cockroachdb
            - sqlserver
      required:
        - databaseProvider
    Session:
      type: object
      description: A query recording session for performance analysis
      properties:
        id:
          type: string
          description: Unique identifier for the session
        name:
          type: string
          description: Display name of the session
        status:
          type: string
          description: Current status of the session
          enum:
            - active
            - completed
            - expired
        databaseProvider:
          type: string
          description: Database provider used during the session
          enum:
            - postgresql
            - mysql
            - cockroachdb
            - sqlserver
        queryCount:
          type: integer
          description: Total number of queries captured
          minimum: 0
        totalDuration:
          type: number
          format: float
          description: Total query execution time in milliseconds
        startedAt:
          type: string
          format: date-time
          description: When the recording session started
        endedAt:
          type: string
          format: date-time
          description: When the recording session ended (null if active)
      required:
        - id
        - status
        - databaseProvider
        - queryCount
        - startedAt
    RecordedQuery:
      type: object
      description: A query captured during a recording session
      properties:
        id:
          type: string
          description: Unique identifier for the recorded query
        sessionId:
          type: string
          description: Identifier of the parent session
        operation:
          type: string
          description: The Prisma Client operation that was executed
          enum:
            - findUnique
            - findFirst
            - findMany
            - create
            - createMany
            - update
            - updateMany
            - upsert
            - delete
            - deleteMany
            - count
            - aggregate
            - groupBy
            - queryRaw
            - executeRaw
        model:
          type: string
          description: The Prisma model the query operates on
          examples:
            - User
            - Post
        sql:
          type: string
          description: The generated SQL query
        duration:
          type: number
          format: float
          description: Query execution time in milliseconds
        timestamp:
          type: string
          format: date-time
          description: When the query was executed
        params:
          type: object
          description: Query parameters (sanitized)
          additionalProperties: true
      required:
        - id
        - sessionId
        - operation
        - duration
        - timestamp
    Recommendation:
      type: object
      description: An AI-powered optimization recommendation for a query pattern
      properties:
        id:
          type: string
          description: Unique identifier for the recommendation
        severity:
          type: string
          description: Severity level of the recommendation
          enum:
            - critical
            - warning
            - info
        category:
          type: string
          description: Category of the optimization
          enum:
            - indexing
            - query_structure
            - caching
            - select_optimization
            - n_plus_one
            - batch_operation
            - connection_management
        title:
          type: string
          description: Short title summarizing the recommendation
          examples:
            - Add index on User.email for faster lookups
        description:
          type: string
          description: Detailed explanation of the issue and recommended fix
        affectedQueries:
          type: array
          description: Query IDs that this recommendation applies to
          items:
            type: string
        suggestedAction:
          type: string
          description: Specific code or schema change to implement
        estimatedImpact:
          type: string
          description: Expected performance improvement
          enum:
            - high
            - medium
            - low
      required:
        - id
        - severity
        - category
        - title
        - description
    SessionMetrics:
      type: object
      description: Aggregated performance metrics for a recording session
      properties:
        sessionId:
          type: string
          description: Identifier of the session
        totalQueries:
          type: integer
          description: Total number of queries in the session
        totalDuration:
          type: number
          format: float
          description: Total execution time of all queries in milliseconds
        averageDuration:
          type: number
          format: float
          description: Average query execution time in milliseconds
        maxDuration:
          type: number
          format: float
          description: Maximum single query execution time in milliseconds
        minDuration:
          type: number
          format: float
          description: Minimum single query execution time in milliseconds
        queryTypeDistribution:
          type: object
          description: Count of queries by operation type
          additionalProperties:
            type: integer
        modelDistribution:
          type: object
          description: Count of queries by model name
          additionalProperties:
            type: integer
        slowestQueries:
          type: array
          description: Top 10 slowest queries by execution duration
          items:
            $ref: '#/components/schemas/RecordedQuery'
          maxItems: 10
      required:
        - sessionId
        - totalQueries
        - totalDuration
        - averageDuration
    QueryIngestPayload:
      type: object
      description: >-
        Payload sent by the Optimize extension containing query execution data
      properties:
        sessionId:
          type: string
          description: Active session to associate the queries with
        queries:
          type: array
          description: Array of query execution records
          items:
            type: object
            properties:
              operation:
                type: string
                description: Prisma Client operation name
              model:
                type: string
                description: Model name
              sql:
                type: string
                description: Generated SQL
              duration:
                type: number
                format: float
                description: Execution duration in milliseconds
              timestamp:
                type: string
                format: date-time
                description: Execution timestamp
            required:
              - operation
              - duration
              - timestamp
      required:
        - sessionId
        - queries
    Error:
      type: object
      description: Standard error response
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
          required:
            - code
            - message
  responses:
    BadRequest:
      description: The request was invalid or malformed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'