Prisma Recommendations API

openapi: 3.2.0
info:
  title: Prisma Optimize Recommendations 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
servers:
- url: https://optimize.prisma-data.net
  description: Prisma Optimize production endpoint
security:
- apiKeyAuth: []
tags:
- name: Recommendations
  description: AI-powered query optimization recommendations
paths:
  /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'
components:
  schemas:
    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
    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
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      description: Unique identifier of the recording session
      schema:
        type: string
  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.
externalDocs:
  description: Prisma Optimize Documentation
  url: https://www.prisma.io/docs/optimize