Prisma Subscriptions API

openapi: 3.2.0
info:
  title: Prisma Pulse Subscriptions API
  description: API for Prisma Pulse, a managed Change Data Capture (CDC) service that enables real-time database change events and type-safe subscriptions via Prisma Client. Pulse captures PostgreSQL logical replication events and delivers them through stream() and subscribe() methods. The stream() API provides at-least-once delivery with ordering guarantees and resumability, while subscribe() provides at-most-once delivery for simpler use cases. Events include create, update, and delete operations with full or partial record data depending on PostgreSQL REPLICA IDENTITY configuration.
  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://pulse.prisma-data.net
  description: Prisma Pulse production endpoint
security:
- apiKeyAuth: []
tags:
- name: Subscriptions
  description: Transient event subscriptions with at-most-once delivery. Missed events during downtime are not recovered.
paths:
  /subscribe:
    post:
      operationId: createSubscription
      summary: Prisma Create a transient event subscription
      description: Creates a transient subscription to database change events for a specific model. The subscribe() method provides at-most-once delivery with no ordering guarantees. Events that occur while the subscriber is disconnected are not recovered. For guaranteed delivery, use the stream() API instead.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '200':
          description: Subscription opened successfully. Events are delivered as server-sent events.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/PulseEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    BadRequest:
      description: The request was invalid or malformed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PulseError'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PulseError'
    InternalServerError:
      description: An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PulseError'
  schemas:
    EventFilter:
      type: object
      description: Filters to apply to event subscriptions. Filters can target specific event types and field values.
      properties:
        create:
          type: object
          description: Filter conditions for create events based on scalar fields
          additionalProperties: true
        update:
          type: object
          description: Filter conditions for update events. Uses the after field to filter on post-update values.
          properties:
            after:
              type: object
              description: Filter on field values after the update
              additionalProperties: true
        delete:
          type: object
          description: Filter conditions for delete events based on scalar fields
          additionalProperties: true
    PulseError:
      type: object
      description: Error response from the Pulse service
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description
        meta:
          type: object
          description: Additional error context
          additionalProperties: true
      required:
      - code
      - message
    SubscriptionRequest:
      type: object
      description: Request to create a transient event subscription
      properties:
        model:
          type: string
          description: The Prisma model name to subscribe to
          examples:
          - User
        filter:
          $ref: '#/components/schemas/EventFilter'
      required:
      - model
    PulseEvent:
      type: object
      description: A database change event captured by Prisma Pulse. The structure varies depending on the action type.
      discriminator:
        propertyName: action
        mapping:
          create: '#/components/schemas/PulseCreateEvent'
          update: '#/components/schemas/PulseUpdateEvent'
          delete: '#/components/schemas/PulseDeleteEvent'
      properties:
        id:
          type: string
          description: Unique ULID identifier for the event
          pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
        action:
          type: string
          description: The type of database operation that triggered the event
          enum:
          - create
          - update
          - delete
        modelName:
          type: string
          description: Name of the Prisma model the event relates to
      required:
      - id
      - action
      - modelName
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key for Pulse authentication provided as a Bearer token. Generated from the Prisma Data Platform Console for each environment.
externalDocs:
  description: Prisma Pulse Documentation
  url: https://www.prisma.io/docs/pulse/database-events