OpenPost Engagement API

The Engagement API from OpenPost — 8 operation(s) for engagement.

GitHub OpenAPI

Operations 8

GET /engagement List stored replies and comments #
POST /engagement/read Mark all matching engagement read across every page #
POST /engagement/refresh Queue engagement collection #
POST /engagement/state Mark engagement read or archived #
GET /engagement/{id}/automation Inspect automatic replies for a comment #
POST /engagement/{id}/automation/stop Take over a comment and stop pending automatic replies #
GET /engagement/{item_id} Read a stored comment and its known parent chain #
POST /engagement/{item_id}/actions Queue a reply or moderation action #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/openpo-st:openpo-st-engagement-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openpo-st-engagement-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  contact:
    email: hello@openpo.st
    name: OpenPost support
    url: https://openpo.st/contact
  description: OpenPost HTTP API for workspace-scoped social publishing. Use it to inspect accounts and provider readiness, manage media and publications, schedule work, and read publishing results. Every operation still follows token scopes, workspace roles, plan limits, provider capabilities, and destination validation.
  license:
    identifier: AGPL-3.0-only
    name: AGPL-3.0-only
  termsOfService: https://openpo.st/terms
  title: OpenPost Engagement API
  version: 1.0.0
servers:
- description: OpenPost Hosted service
  url: https://app.openpo.st/api/v1
- description: The OpenPost instance serving this contract
  url: /api/v1
security:
- bearerAuth: []
- sessionCookie: []
tags:
- name: Engagement
paths:
  /engagement:
    get:
      operationId: list-engagement
      parameters:
      - description: Filter account activity by kind; omit for all engagement
        explode: false
        in: query
        name: kind
        schema:
          description: Filter account activity by kind; omit for all engagement
          enum:
          - comment
          - mention
          - review
          type: string
      - explode: false
        in: query
        name: workspace_id
        required: true
        schema:
          type: string
      - explode: false
        in: query
        name: platform
        schema:
          type: string
      - explode: false
        in: query
        name: account_id
        schema:
          type: string
      - explode: false
        in: query
        name: publication_id
        schema:
          type: string
      - explode: false
        in: query
        name: unread_only
        schema:
          type: boolean
      - explode: false
        in: query
        name: archived
        schema:
          type: boolean
      - explode: false
        in: query
        name: limit
        schema:
          default: 50
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - explode: false
        in: query
        name: offset
        schema:
          default: 0
          format: int64
          minimum: 0
          type: integer
      - description: Opaque cursor for stable older-page pagination
        explode: false
        in: query
        name: cursor
        schema:
          description: Opaque cursor for stable older-page pagination
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementPage'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: List stored replies and comments
      tags:
      - Engagement
      x-openpost-automation:
        access: read
        effect: query
        exposure: alpha
        idempotency: none
        retry: transient
        selectors:
        - label_path: name
          operation_id: list-workspaces
          parameter: workspace_id
          value_path: id
        - label_path: account_username
          operation_id: list-accounts
          parameter: account_id
          value_path: id
  /engagement/read:
    post:
      operationId: mark-engagement-read
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkEngagementReadInputBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkEngagementReadOutputBody'
          description: OK
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
      summary: Mark all matching engagement read across every page
      tags:
      - Engagement
      x-openpost-automation:
        access: write
        effect: local-mutation
        exposure: disabled
        idempotency: none
        retry: never
  /engagement/refresh:
    post:
      operationId: refresh-engagement
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshCapabilitiesInputBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshCapabilityOutcome'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: Queue engagement collection
      tags:
      - Engagement
  /engagement/state:
    post:
      operationId: set-engagement-state
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEngagementStateInputBody'
        required: true
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: Mark engagement read or archived
      tags:
      - Engagement
  /engagement/{id}/automation:
    get:
      operationId: list-engagement-automation
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - explode: false
        in: query
        name: workspace_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AutomationReply'
                type:
                - array
                - 'null'
          description: OK
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
      summary: Inspect automatic replies for a comment
      tags:
      - Engagement
      x-openpost-automation:
        access: read
        effect: query
        exposure: disabled
        idempotency: none
        retry: transient
  /engagement/{id}/automation/stop:
    post:
      operationId: stop-engagement-automation
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - explode: false
        in: query
        name: workspace_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AutomationReply'
                type:
                - array
                - 'null'
          description: OK
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
      summary: Take over a comment and stop pending automatic replies
      tags:
      - Engagement
      x-openpost-automation:
        access: write
        effect: local-mutation
        exposure: disabled
        idempotency: none
        retry: never
  /engagement/{item_id}:
    get:
      operationId: get-engagement-item
      parameters:
      - in: path
        name: item_id
        required: true
        schema:
          type: string
      - explode: false
        in: query
        name: workspace_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementDetail'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: Read a stored comment and its known parent chain
      tags:
      - Engagement
      x-openpost-automation:
        access: read
        effect: query
        exposure: disabled
        idempotency: none
        retry: transient
  /engagement/{item_id}/actions:
    post:
      operationId: queue-engagement-action
      parameters:
      - in: path
        name: item_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EngagementActionInputBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementActionOutputBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      summary: Queue a reply or moderation action
      tags:
      - Engagement
components:
  schemas:
    EngagementAttachment:
      additionalProperties: false
      properties:
        alt_text:
          type: string
        mime_type:
          type: string
        name:
          type: string
        thumbnail:
          type: string
        type:
          type: string
        url:
          type: string
      required:
      - type
      - url
      type: object
    EngagementSubject:
      additionalProperties: false
      properties:
        kind:
          type: string
        parent:
          $ref: '#/components/schemas/PostReference'
        remote_id:
          type: string
        review:
          $ref: '#/components/schemas/ReviewContext'
        root:
          $ref: '#/components/schemas/PostReference'
        url:
          type: string
        visibility:
          type: string
      required:
      - kind
      - remote_id
      type: object
    SetEngagementStateInputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/SetEngagementStateInputBody.json
          format: uri
          readOnly: true
          type: string
        archived:
          type: boolean
        ids:
          items:
            type: string
          type:
          - array
          - 'null'
        read:
          type: boolean
        workspace_id:
          type: string
      required:
      - workspace_id
      - ids
      type: object
    RefreshCapabilityOutcome:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/RefreshCapabilityOutcome.json
          format: uri
          readOnly: true
          type: string
        error_code:
          type: string
        job_ids:
          description: Durable collection jobs to observe before presenting upstream refresh completion
          items:
            type: string
          type:
          - array
          - 'null'
        queued:
          format: int64
          type: integer
        status:
          enum:
          - queued
          - failed
          - unavailable
          type: string
      required:
      - status
      - queued
      type: object
    RefreshCapabilitiesInputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/RefreshCapabilitiesInputBody.json
          format: uri
          readOnly: true
          type: string
        workspace_id:
          type: string
      required:
      - workspace_id
      type: object
    EngagementActionInputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/EngagementActionInputBody.json
          format: uri
          readOnly: true
          type: string
        action:
          enum:
          - reply
          - delete_reply
          - hide
          - delete
          - like
          - unlike
          type: string
        client_operation_id:
          maxLength: 128
          type: string
        message:
          type: string
        workspace_id:
          type: string
      required:
      - workspace_id
      - action
      type: object
    ReviewContext:
      additionalProperties: false
      properties:
        anonymous:
          type: boolean
        owner_reply:
          $ref: '#/components/schemas/ReviewReply'
        stars:
          format: int64
          type: integer
      required:
      - anonymous
      type: object
    EngagementPage:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/EngagementPage.json
          format: uri
          readOnly: true
          type: string
        items:
          items:
            $ref: '#/components/schemas/EngagementItem'
          type:
          - array
          - 'null'
        next_cursor:
          type: string
        sync_states:
          items:
            $ref: '#/components/schemas/EngagementSyncState'
          type:
          - array
          - 'null'
        total:
          format: int64
          type: integer
      required:
      - items
      - total
      - sync_states
      type: object
    EngagementDetail:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/EngagementDetail.json
          format: uri
          readOnly: true
          type: string
        item:
          $ref: '#/components/schemas/EngagementItem'
        parents:
          items:
            $ref: '#/components/schemas/EngagementItem'
          type:
          - array
          - 'null'
      required:
      - item
      - parents
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/ErrorModel.json
          format: uri
          readOnly: true
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
          - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
          - array
          - 'null'
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
          - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
          - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
          - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
          - https://example.com/errors/example
          format: uri
          type: string
      type: object
    MarkEngagementReadInputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/MarkEngagementReadInputBody.json
          format: uri
          readOnly: true
          type: string
        account_id:
          type: string
        archived:
          type: boolean
        kind:
          enum:
          - comment
          - mention
          - review
          type: string
        platform:
          type: string
        publication_id:
          type: string
        workspace_id:
          type: string
      required:
      - workspace_id
      type: object
    EngagementItem:
      additionalProperties: false
      properties:
        account_username:
          type: string
        archived_at:
          format: date-time
          type: string
        attachments:
          items:
            $ref: '#/components/schemas/EngagementAttachment'
          type:
          - array
          - 'null'
        author_avatar_url:
          type: string
        author_handle:
          type: string
        author_name:
          type: string
        author_remote_id:
          type: string
        automation_run_id:
          type: string
        automation_state:
          type: string
        automation_stopped_at:
          format: date-time
          type: string
        body:
          type: string
        can_delete:
          type: boolean
        can_delete_reply:
          type: boolean
        can_hide:
          type: boolean
        can_like:
          type: boolean
        can_reply:
          type: boolean
        can_unlike:
          type: boolean
        conversation_remote_id:
          type: string
        created_at:
          format: date-time
          type: string
        deleted_at:
          format: date-time
          type: string
        edited_at:
          format: date-time
          type: string
        hidden:
          type: boolean
        id:
          type: string
        is_ours:
          type: boolean
        kind:
          type: string
        last_seen_at:
          format: date-time
          type: string
        liked:
          type: boolean
        parent_remote_id:
          type: string
        platform:
          type: string
        provider_post_url:
          type: string
        publication_excerpt:
          type: string
        publication_id:
          type: string
        publication_title:
          type: string
        read_at:
          format: date-time
          type: string
        remote_created_at:
          format: date-time
          type: string
        remote_id:
          type: string
        rendition_id:
          type: string
        replied_at:
          format: date-time
          type: string
        reply_job_id:
          type: string
        reply_operation_state:
          type: string
        social_account_id:
          type: string
        subject:
          $ref: '#/components/schemas/EngagementSubject'
        updated_at:
          format: date-time
          type: string
        workspace_id:
          type: string
      required:
      - id
      - workspace_id
      - social_account_id
      - platform
      - remote_id
      - parent_remote_id
      - conversation_remote_id
      - author_remote_id
      - author_name
      - author_handle
      - author_avatar_url
      - body
      - is_ours
      - can_reply
      - can_hide
      - can_delete
      - can_like
      - can_unlike
      - liked
      - hidden
      - last_seen_at
      - created_at
      - updated_at
      - attachments
      type: object
    EngagementActionOutputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/EngagementActionOutputBody.json
          format: uri
          readOnly: true
          type: string
        job_id:
          type: string
      required:
      - job_id
      type: object
    AutomationReply:
      additionalProperties: false
      properties:
        body:
          type: string
        channel:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: string
        item_id:
          type: string
        job_id:
          type: string
        run_id:
          type: string
        state:
          type: string
        step_id:
          type: string
        updated_at:
          format: date-time
          type: string
        workflow_id:
          type: string
        workspace_id:
          type: string
      required:
      - id
      - workspace_id
      - item_id
      - workflow_id
      - run_id
      - step_id
      - channel
      - body
      - state
      - created_at
      - updated_at
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    PostReference:
      additionalProperties: false
      properties:
        cid:
          type: string
        uri:
          type: string
      required:
      - uri
      - cid
      type: object
    MarkEngagementReadOutputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/api/v1/schemas/MarkEngagementReadOutputBody.json
          format: uri
          readOnly: true
          type: string
        updated_count:
          description: Number of matching unread items marked read across all pages. Read state is shared by the Workspace.
          format: int64
          type: integer
      required:
      - updated_count
      type: object
    ReviewReply:
      additionalProperties: false
      properties:
        policy_violation:
          type: string
        state:
          type: string
        text:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - text
      - state
      type: object
    EngagementSyncState:
      additionalProperties: false
      properties:
        error_code:
          type: string
        error_message:
          type: string
        feed:
          type: string
        id:
          type: string
        last_success_at:
          format: date-time
          type: string
        next_sync_at:
          format: date-time
          type: string
        platform:
          type: string
        rendition_id:
          type: string
        social_account_id:
          type: string
        status:
          type: string
      required:
      - id
      - rendition_id
      - social_account_id
      - platform
      - status
      - error_code
      - error_message
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: OpenPost API token or session JWT
      scheme: bearer
      type: http
    sessionCookie:
      in: cookie
      name: openpost_session
      type: apiKey