Paragon Sync API

openapi: 3.2.0
info:
  title: Paragon Managed Sync API
  description: Managed Sync provides pipelines to sync data from your users' integration sources (File Storage, CRM, Ticketing) into your app or RAG pipeline. The service handles sync scheduling, normalization to standardized schemas, and enforcement of source-system permissions. Managed Sync exposes a Sync API for record ingestion and a Permissions API for ReBAC-style access checks over synced objects.
  version: 1.0.0
  contact:
    name: Paragon
    url: https://www.useparagon.com
  license:
    name: Proprietary
    url: https://www.useparagon.com/terms-of-service
servers:
- url: https://managed-sync.useparagon.com
  description: Paragon Managed Sync API (Cloud)
security:
- bearerAuth: []
tags:
- name: Sync
  description: Enable, monitor, and read records from Managed Sync pipelines.
paths:
  /projects/{projectId}/sync/enable:
    post:
      operationId: enableSync
      summary: Paragon Enable A Sync
      description: Enables a sync pipeline for a Connected User and integration. Paragon begins fetching records on a configurable schedule.
      tags:
      - Sync
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - integration
              - syncType
              properties:
                integration:
                  type: string
                  description: Integration identifier (e.g., googleDrive, salesforce).
                syncType:
                  type: string
                  description: The sync pipeline type (e.g., files, contacts, deals, tickets).
                frequency:
                  type: string
                  description: Sync frequency (e.g., 1m, 15m, 1h, 1d).
      responses:
        '201':
          description: Sync enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncStatus'
  /projects/{projectId}/sync/status:
    get:
      operationId: getSyncStatus
      summary: Paragon Get Sync Status
      description: Returns the state of a sync pipeline for the Connected User.
      tags:
      - Sync
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: integration
        in: query
        required: true
        schema:
          type: string
      - name: syncType
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Sync status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncStatus'
  /projects/{projectId}/sync/records:
    get:
      operationId: pullSyncedRecords
      summary: Paragon Pull Synced Records
      description: Returns a paginated list of normalized records for a given integration and sync type (e.g., Files, Contacts, Deals, Tickets).
      tags:
      - Sync
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: integration
        in: query
        required: true
        schema:
          type: string
      - name: syncType
        in: query
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of synced records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      $ref: '#/components/schemas/SyncedRecord'
                  nextCursor:
                    type: string
  /projects/{projectId}/sync/records/{recordId}:
    get:
      operationId: getSyncedRecord
      summary: Paragon Get Synced Record
      description: Returns a single normalized synced record by ID.
      tags:
      - Sync
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: recordId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The synced record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncedRecord'
  /projects/{projectId}/sync/records/{recordId}/content:
    get:
      operationId: downloadContent
      summary: Paragon Download File Content
      description: Downloads the binary content of a file-type synced record. Returns the raw file bytes with the appropriate Content-Type for the source file.
      tags:
      - Sync
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: recordId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: File content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
components:
  schemas:
    SyncedRecord:
      type: object
      description: A normalized record produced by a Managed Sync pipeline.
      properties:
        id:
          type: string
        integration:
          type: string
        syncType:
          type: string
        sourceId:
          type: string
        data:
          type: object
          additionalProperties: true
        permissions:
          type: object
          description: Source-system permissions captured for this record.
          additionalProperties: true
        updatedAt:
          type: string
          format: date-time
    SyncStatus:
      type: object
      properties:
        integration:
          type: string
        syncType:
          type: string
        status:
          type: string
          enum:
          - SYNCING
          - IDLE
          - ERROR
          - DISABLED
        lastSyncedAt:
          type: string
          format: date-time
        recordCount:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Paragon User Token (JWT) Bearer.