openapi: 3.2.0
info:
  title: Ploid Monitors API
  version: 2.0.0
  description: 'Operations tagged Monitors across 2 of this provider''s published API definitions: ploid-openapi.json, ploid-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ploid.com
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Monitors
paths:
  /v1/monitors/compile:
    post:
      operationId: compileMonitor
      summary: Preview a monitor plan and output schema
      description: Compiles a natural-language query into targets, events and relevance criteria, and derives an output schema when `output.type` is `object` without a schema. Creates nothing. Compile and create cost 1 ACU. Each run costs 1 ACU per target fetched plus 1 ACU per emitted item. Baseline runs emit nothing.
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCompileRequest'
      responses:
        '200':
          description: Compiled plan
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/MonitorCompilation'
                  meta:
                    type: object
                    additionalProperties: true
        '402':
          description: Insufficient ACU
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    servers:
    - url: https://api.ploid.com
  /v1/monitors:
    post:
      operationId: createMonitor
      summary: Create a social monitor
      description: Creates a scheduled monitor over LinkedIn, X, Instagram and TikTok and starts a silent baseline run. `meta.baseline_run_id` identifies that run; `meta.unresolved` lists mentions that could not be turned into a target. Compile and create cost 1 ACU. Each run costs 1 ACU per target fetched plus 1 ACU per emitted item. Baseline runs emit nothing.
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCreateRequest'
      responses:
        '201':
          description: Monitor created
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Monitor'
                  meta:
                    type: object
                    additionalProperties: true
        '400':
          description: Invalid webhook URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '402':
          description: Insufficient ACU or API-key budget
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '409':
          description: The workspace already has 50 monitors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '422':
          description: Validation failed or no targets resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    get:
      operationId: listMonitors
      summary: List monitors
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      responses:
        '200':
          description: Monitors, newest first (up to 100)
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Monitor'
                  meta:
                    type: object
                    additionalProperties: true
    servers:
    - url: https://api.ploid.com
  /v1/monitors/{id}:
    get:
      operationId: getMonitor
      summary: Get a monitor
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Monitor
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Monitor'
                  meta:
                    type: object
                    additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    patch:
      operationId: updateMonitor
      summary: Update, pause or resume a monitor
      description: Changing `query` recompiles the plan; passing `plan` replaces the targets. Either starts a new baseline run.
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorUpdateRequest'
      responses:
        '200':
          description: Updated monitor
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Monitor'
                  meta:
                    type: object
                    additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '409':
          description: Monitor deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    delete:
      operationId: deleteMonitor
      summary: Delete (disable) a monitor
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Monitor disabled
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    servers:
    - url: https://api.ploid.com
  /v1/monitors/{id}/run:
    post:
      operationId: runMonitor
      summary: Trigger a run now
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Run queued
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/MonitorRun'
                  meta:
                    type: object
                    additionalProperties: true
        '402':
          description: Insufficient ACU or API-key budget
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '409':
          description: A run is already in progress, or the monitor is deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    servers:
    - url: https://api.ploid.com
  /v1/monitors/{id}/runs:
    get:
      operationId: listMonitorRuns
      summary: List runs
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: '`next_cursor` from the previous page.'
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Runs, newest first
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MonitorRun'
                  meta:
                    type: object
                    additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    servers:
    - url: https://api.ploid.com
  /v1/monitors/{id}/runs/{runId}:
    get:
      operationId: getMonitorRun
      summary: Get a run
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/MonitorRun'
                  meta:
                    type: object
                    additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    servers:
    - url: https://api.ploid.com
  /v1/monitors/{id}/items:
    get:
      operationId: listMonitorItems
      summary: List emitted items
      tags:
      - Monitors
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: run_id
        in: query
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: '`next_cursor` from the previous page.'
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Items, newest first
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MonitorItem'
                  meta:
                    type: object
                    additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    servers:
    - url: https://api.ploid.com
components:
  schemas:
    PublicApiError:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
            http_status:
              type: integer
              minimum: 400
              maximum: 599
              description: Semantic status when an error terminates a response after streaming headers opened.
            retryable:
              type: boolean
            unavailable_fields:
              type: array
              items:
                type: string
                enum:
                - work_email
                - personal_email
                - phone
                - profile
                - email
              description: Requested enrichment fields that could not complete. Present when all requested fields are unavailable.
            usage:
              type: object
              additionalProperties: false
              required:
              - acu_used
              - billed
              - free
              - not_found
              properties:
                acu_used:
                  type: number
                  minimum: 0
                acu_remaining:
                  type: number
                  minimum: 0
                acu_value_usd:
                  type: number
                  const: 0.1
                billed:
                  type: array
                  items:
                    type: string
                free:
                  type: array
                  items:
                    type: string
                not_found:
                  type: array
                  items:
                    type: string
          additionalProperties: true
    MonitorPlan:
      type: object
      required:
      - targets
      properties:
        targets:
          type: array
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/MonitorTarget'
        relevance_criteria:
          type:
          - string
          - 'null'
          description: Every item must satisfy this to be emitted. Null emits all new activity.
    MonitorCompileRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          maxLength: 1000
          example: New LinkedIn posts from Nvidia about AI chips
        output:
          $ref: '#/components/schemas/MonitorOutput'
    MonitorCreateRequest:
      type: object
      required:
      - query
      - schedule
      properties:
        query:
          type: string
          maxLength: 1000
        schedule:
          $ref: '#/components/schemas/MonitorSchedule'
        name:
          type: string
          maxLength: 120
        output:
          $ref: '#/components/schemas/MonitorOutput'
        plan:
          $ref: '#/components/schemas/MonitorPlan'
        webhook_url:
          type: string
          format: uri
        max_items_per_run:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
    MonitorRun:
      type: object
      properties:
        object:
          type: string
          const: monitor_run
        id:
          type: string
        monitor_id:
          type: string
        trigger:
          type: string
          enum:
          - baseline
          - schedule
          - manual
        status:
          type: string
          enum:
          - queued
          - running
          - completed
          - failed
          - skipped
          description: '`skipped` means available ACU or the API-key budget could not cover the run; `error` explains which.'
        candidates:
          type: integer
        items_emitted:
          type: integer
        acu_charged:
          type: number
        error:
          type:
          - string
          - 'null'
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    MonitorUpdateRequest:
      type: object
      minProperties: 1
      properties:
        name:
          type: string
          maxLength: 120
        status:
          type: string
          enum:
          - active
          - paused
        query:
          type: string
          maxLength: 1000
        schedule:
          $ref: '#/components/schemas/MonitorSchedule'
        output:
          $ref: '#/components/schemas/MonitorOutput'
        plan:
          $ref: '#/components/schemas/MonitorPlan'
        webhook_url:
          type:
          - string
          - 'null'
          format: uri
        max_items_per_run:
          type: integer
          minimum: 1
          maximum: 100
    Monitor:
      type: object
      properties:
        object:
          type: string
          const: monitor
        id:
          type: string
        name:
          type: string
        query:
          type: string
        status:
          type: string
          enum:
          - active
          - paused
          - disabled
        schedule:
          type: object
          properties:
            preset:
              type:
              - string
              - 'null'
            cron:
              type: string
            timezone:
              type: string
        targets:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/MonitorTarget'
            - properties:
                id:
                  type: string
        relevance_criteria:
          type:
          - string
          - 'null'
        output:
          type: object
          properties:
            type:
              type: string
            schema:
              type: object
              additionalProperties: true
        webhook_url:
          type:
          - string
          - 'null'
        max_items_per_run:
          type: integer
        baseline_at:
          type:
          - string
          - 'null'
          format: date-time
        last_run_at:
          type:
          - string
          - 'null'
          format: date-time
        next_run_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    MonitorSchedule:
      oneOf:
      - type: object
        required:
        - preset
        additionalProperties: false
        properties:
          preset:
            type: string
            enum:
            - hourly
            - daily
            - weekly
          timezone:
            type: string
            default: UTC
      - type: object
        required:
        - cron
        additionalProperties: false
        properties:
          cron:
            type: string
            description: Five-field cron. The minute field must be a single value, so runs happen at most hourly.
          timezone:
            type: string
            default: UTC
    MonitorItem:
      type: object
      description: 'Webhook events: monitor.run.completed, monitor.run.failed, monitor.run.skipped. monitor.run.completed is sent only when a run emits items and carries up to 100 of them.'
      properties:
        object:
          type: string
          const: monitor_item
        id:
          type: string
        monitor_id:
          type: string
        run_id:
          type: string
        platform:
          type: string
          enum:
          - linkedin
          - x
          - instagram
          - tiktok
        event:
          type: string
          enum:
          - post.created
          - engagement.created
          - profile.changed
          - company.changed
          - job.posted
        target:
          type: object
          properties:
            id:
              type:
              - string
              - 'null'
            kind:
              type:
              - string
              - 'null'
            identifier:
              type:
              - string
              - 'null'
        url:
          type:
          - string
          - 'null'
        occurred_at:
          type:
          - string
          - 'null'
          format: date-time
        relevance:
          type:
          - object
          - 'null'
          properties:
            score:
              type: number
            reason:
              type: string
        output:
          description: Object matching the monitor's output schema, or null when extraction failed.
        output_error:
          type:
          - string
          - 'null'
        source:
          type: object
          additionalProperties: true
          description: Normalized text, author, metrics and event details.
        created_at:
          type: string
          format: date-time
    MonitorOutput:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - text
          - object
          description: '`text` returns `{ summary }` per item. `object` returns the schema you give or one derived from the query.'
        schema:
          type: object
          additionalProperties: true
          description: JSON Schema with an object root, at most 25 properties.
        description:
          type: string
          description: Describe the fields in prose, or paste example JSON or a JSON Schema, to derive `schema`.
    MonitorCompilation:
      type: object
      required:
      - object
      - name
      - plan
      - output
      - unresolved
      properties:
        object:
          type: string
          const: monitor_compilation
        name:
          type: string
        plan:
          $ref: '#/components/schemas/MonitorPlan'
        output:
          type: object
          required:
          - type
          - schema
          properties:
            type:
              type: string
            schema:
              type: object
              additionalProperties: true
        unresolved:
          type: array
          items:
            type: object
            properties:
              platform:
                type:
                - string
                - 'null'
              kind:
                type:
                - string
                - 'null'
              mention:
                type: string
              reason:
                type: string
    MonitorTarget:
      type: object
      required:
      - platform
      - kind
      - identifier
      properties:
        platform:
          type: string
          enum:
          - linkedin
          - x
          - instagram
          - tiktok
        kind:
          type: string
          enum:
          - profile
          - company
          - keyword
          - hashtag
          description: '`company` is LinkedIn-only; elsewhere brand accounts are profiles.'
        identifier:
          type: string
          description: 'Profile or company URL or @handle; search terms for keyword; tag without # for hashtag. Instagram supports hashtags but not keyword search.'
        events:
          type: array
          items:
            type: string
            enum:
            - posts
            - engagement
            - profile
            - company
          description: Defaults to posts. Topics support posts only.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
x-refined-from:
- ploid-openapi.json
- ploid-openapi.yml