openapi: 3.1.0
info:
  title: Outbrain Engage API
  description: >
    The Outbrain Engage API powers content recommendation widgets across the
    open web. It is the publisher-facing interface for retrieving personalized
    content recommendations (organic + sponsored) to render in Outbrain
    widgets. Used by the Outbrain JS Widget, the Mobile SDK (iOS/Android),
    Smartfeed implementations, and app mediation integrations.
  version: '1.0'
  contact:
    name: Outbrain Developer Center
    url: https://developer.outbrain.com
  license:
    name: Outbrain Publisher Terms
    url: https://www.outbrain.com/legal/

servers:
  - url: https://odb.outbrain.com
    description: Production Engage / recommendations endpoint

security:
  - PublisherKeyAuth: []

tags:
  - name: Recommendations
    description: Retrieve content recommendations
  - name: Widgets
    description: Publisher widget configuration
  - name: Events
    description: Impression and click events

paths:
  /utils/get:
    get:
      summary: Get Recommendations For A Widget
      description: >
        Fetch a set of recommended content items for a given publisher widget.
        Recommendations include both organic content and sponsored (paid)
        promoted links. Driven by the publisher key, widget ID, and the page URL.
      operationId: getRecommendations
      tags:
        - Recommendations
      parameters:
        - name: widgetJSId
          in: query
          required: true
          schema:
            type: string
          description: The publisher widget ID (e.g. AR_1, AR_2).
        - name: permalink
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: Canonical URL of the page rendering the widget.
        - name: publisherKey
          in: query
          required: true
          schema:
            type: string
          description: Outbrain publisher key.
        - name: idx
          in: query
          required: false
          schema:
            type: integer
          description: Widget index on the page.
        - name: pageNum
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Recommendations payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationsResponse'

  /report/impression:
    post:
      summary: Report A Widget Impression
      description: Report that an Outbrain widget rendered impressions for one or more recommendations.
      operationId: reportImpression
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImpressionEvent'
      responses:
        '204':
          description: Event recorded.

  /report/click:
    post:
      summary: Report A Recommendation Click
      description: Report a user click on a recommendation served by an Outbrain widget.
      operationId: reportClick
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClickEvent'
      responses:
        '204':
          description: Event recorded.

components:
  securitySchemes:
    PublisherKeyAuth:
      type: apiKey
      in: query
      name: publisherKey

  schemas:
    Recommendation:
      type: object
      properties:
        id:
          type: string
        content:
          type: string
          description: Headline text of the recommendation.
        url:
          type: string
          format: uri
        thumbnail:
          type: object
          properties:
            url:
              type: string
              format: uri
            width:
              type: integer
            height:
              type: integer
        origin:
          type: string
          enum: [ORGANIC, PAID]
        source_name:
          type: string
        publish_date:
          type: string
          format: date-time
        disclosure:
          type: object
          properties:
            informationUrl:
              type: string
              format: uri
            prefix:
              type: string

    RecommendationsResponse:
      type: object
      properties:
        request:
          type: object
          properties:
            success:
              type: boolean
            id:
              type: string
        settings:
          type: object
        response:
          type: object
          properties:
            recommendations:
              type: array
              items:
                $ref: '#/components/schemas/Recommendation'

    ImpressionEvent:
      type: object
      required: [widgetJSId, publisherKey, recommendationIds]
      properties:
        widgetJSId:
          type: string
        publisherKey:
          type: string
        recommendationIds:
          type: array
          items:
            type: string
        permalink:
          type: string
          format: uri

    ClickEvent:
      type: object
      required: [widgetJSId, publisherKey, recommendationId]
      properties:
        widgetJSId:
          type: string
        publisherKey:
          type: string
        recommendationId:
          type: string
        permalink:
          type: string
          format: uri