openapi: 3.2.0
info:
  title: LDM v3 Phantom Browser API
  description: 'Multi-tenant B2B outreach automation platform. Auth: JWT Bearer (15-min) or tenant API key (ldm_*) managed in CRM Settings → API Keys. All tenant-scoped endpoints require the X-Tenant-Id header.'
  version: 1.0.0
  contact: {}
servers:
- url: https://api.live-direct-marketing.online
  description: Production
- url: https://api.dev.live-direct-marketing.online
  description: Development
- url: http://127.0.0.1:3000
  description: Local
tags:
- name: Phantom Browser
paths:
  /api/phantom-browser/profiles:
    get:
      operationId: PhantomBrowserController_listProfiles
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: List all Phantom browser profiles
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:read
    post:
      operationId: PhantomBrowserController_createProfile
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Create a new Phantom browser profile
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:write
  /api/phantom-browser/profiles/sync:
    post:
      operationId: PhantomBrowserController_syncProfiles
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Re-send the profiles list to the connected Phantom client
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:write
  /api/phantom-browser/profiles/{id}:
    get:
      operationId: PhantomBrowserController_getProfile
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get a single Phantom browser profile by id
      tags:
      - Phantom Browser
    put:
      operationId: PhantomBrowserController_updateProfile
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Update a Phantom browser profile
      tags:
      - Phantom Browser
    delete:
      operationId: PhantomBrowserController_deleteProfile
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Delete a Phantom browser profile
      tags:
      - Phantom Browser
  /api/phantom-browser/client/status:
    get:
      operationId: PhantomBrowserController_getClientStatus
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get the Phantom desktop client connection status
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:read
  /api/phantom-browser/client/token/regenerate:
    post:
      operationId: PhantomBrowserController_regenerateToken
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Regenerate the Phantom client auth token
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:write
  /api/phantom-browser/profiles/{id}/launch:
    post:
      operationId: PhantomBrowserController_launchProfile
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Launch a profile on the user's Phantom desktop client
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/stop:
    post:
      operationId: PhantomBrowserController_stopProfile
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Stop a running profile on the Phantom desktop client
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/navigate:
    post:
      operationId: PhantomBrowserController_navigate
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Navigate the Phantom browser profile to a URL
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/screenshot:
    post:
      operationId: PhantomBrowserController_screenshot
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Take a screenshot in the Phantom browser profile (base64 JPEG)
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/screenshot.jpg:
    get:
      operationId: PhantomBrowserController_screenshotImage
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get the latest Phantom browser screenshot as a JPEG image
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/html:
    get:
      operationId: PhantomBrowserController_getHtml
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get the current Phantom browser page's HTML
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/page-info:
    get:
      operationId: PhantomBrowserController_getPageInfo
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get the current Phantom browser page URL and title
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/execute:
    post:
      operationId: PhantomBrowserController_executeJs
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Execute JavaScript in the Phantom browser page context
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/click:
    post:
      operationId: PhantomBrowserController_click
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Click an element in the Phantom browser by CSS selector
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/type:
    post:
      operationId: PhantomBrowserController_typeText
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Type text into a focused element or selector in the Phantom browser
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/cookies:
    get:
      operationId: PhantomBrowserController_getCookies
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get cookies for the current Phantom browser page
      tags:
      - Phantom Browser
    post:
      operationId: PhantomBrowserController_setCookies
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Set cookies on the current Phantom browser page — lets the worker browse a site…
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/scroll:
    post:
      operationId: PhantomBrowserController_scroll
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Scroll the current Phantom browser page
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/wait:
    post:
      operationId: PhantomBrowserController_waitFor
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Wait for a selector to appear in the Phantom browser page
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/solve-captcha:
    post:
      operationId: PhantomBrowserController_solveCaptcha
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Solve a captcha on the current Phantom browser page (via RuCaptcha)
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/proxy:
    put:
      operationId: PhantomBrowserController_setProxy
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Set the proxy configuration on a Phantom browser profile
      tags:
      - Phantom Browser
    delete:
      operationId: PhantomBrowserController_removeProxy
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Remove the proxy configuration from a Phantom browser profile
      tags:
      - Phantom Browser
  /api/phantom-browser/profiles/{id}/proxy/test:
    post:
      operationId: PhantomBrowserController_testProxy
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Test a Phantom browser profile proxy (launch and report IP)
      tags:
      - Phantom Browser
  /api/phantom-browser/launches:
    get:
      operationId: PhantomBrowserController_listLaunches
      parameters:
      - name: profileId
        required: true
        in: query
        schema:
          type: string
      - name: limit
        required: true
        in: query
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: List Phantom browser profile launches
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:read
  /api/phantom-browser/scenarios:
    get:
      operationId: PhantomBrowserController_listScenarios
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: List Phantom browser scenarios
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:read
    post:
      operationId: PhantomBrowserController_createScenario
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Create a new Phantom browser scenario
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:write
  /api/phantom-browser/scenarios/{id}:
    get:
      operationId: PhantomBrowserController_getScenario
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get a single Phantom browser scenario by id
      tags:
      - Phantom Browser
    put:
      operationId: PhantomBrowserController_updateScenario
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Update a Phantom browser scenario
      tags:
      - Phantom Browser
    delete:
      operationId: PhantomBrowserController_deleteScenario
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Delete a Phantom browser scenario
      tags:
      - Phantom Browser
  /api/phantom-browser/schedules:
    get:
      operationId: PhantomBrowserController_listSchedules
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: List Phantom browser schedules
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:read
    post:
      operationId: PhantomBrowserController_createSchedule
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Create a new Phantom browser schedule
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:write
  /api/phantom-browser/schedules/{id}:
    put:
      operationId: PhantomBrowserController_updateSchedule
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Update a Phantom browser schedule
      tags:
      - Phantom Browser
    delete:
      operationId: PhantomBrowserController_deleteSchedule
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Delete a Phantom browser schedule
      tags:
      - Phantom Browser
  /api/phantom-browser/admin/stats:
    get:
      operationId: PhantomBrowserController_getAdminStats
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get Phantom browser admin stats (SUPER only)
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:read
  /api/phantom-browser/download/config:
    get:
      operationId: PhantomBrowserController_downloadConfig
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Download the Phantom desktop client config.json with the user's token
      tags:
      - Phantom Browser
      x-required-scope:
      - admin:read
components:
  securitySchemes:
    jwt:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: JWT access token from /auth/login (Bearer <token>)
    tenant-api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Tenant API key (Bearer ldm_*) for MCP/A2A clients. Issued via CRM Settings → API Keys.
    rpa-service:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Dedicated RPA service key. No tenant API-key or query-key authentication.