openapi: 3.2.0
info:
title: top comments API
version: '1.0'
contact:
name: OpenWeb
url: https://www.openweb.com/
description: This API fetches and sorts the top comments from a specific site, article, or user.
servers:
- url: https://api.openweb.com/engagement-api
tags:
- name: top comments
description: Top Comments
paths:
/top-comments-conversation:
get:
summary: List top comments within a specific Conversation
tags:
- top comments
responses:
'200':
$ref: '#/components/responses/CommentObject'
description: Retrieve the top Conversation comments from all time
parameters:
- $ref: '#/components/parameters/x-api-key'
- $ref: '#/components/parameters/x-conversation-id'
- $ref: '#/components/parameters/x-post-id'
- $ref: '#/components/parameters/x-spot-id'
- $ref: '#/components/parameters/x-count'
operationId: getTopCommentsConversation
x-operation-id-source: derived
/top-comments-spot:
get:
summary: List top comments within an entire spot
tags:
- top comments
responses:
'200':
$ref: '#/components/responses/CommentObject'
description: Retrieve the top comments for a Spot ID in a given time period
parameters:
- $ref: '#/components/parameters/x-api-key'
- $ref: '#/components/parameters/x-spot-id'
- $ref: '#/components/parameters/x-count'
- $ref: '#/components/parameters/x-interval'
- $ref: '#/components/parameters/x-month'
- $ref: '#/components/parameters/x-weeks'
- $ref: '#/components/parameters/x-year'
operationId: getTopCommentsSpot
x-operation-id-source: derived
/top-comments-user:
get:
summary: List top comments for an individual user
tags:
- top comments
responses:
'200':
$ref: '#/components/responses/CommentObject'
description: Retrieve the top user comments in a given time period
parameters:
- $ref: '#/components/parameters/x-api-key'
- $ref: '#/components/parameters/x-spot-id'
- $ref: '#/components/parameters/x-user-id'
- $ref: '#/components/parameters/x-count'
- $ref: '#/components/parameters/x-interval'
- $ref: '#/components/parameters/x-month'
- $ref: '#/components/parameters/x-weeks'
- $ref: '#/components/parameters/x-year'
operationId: getTopCommentsUser
x-operation-id-source: derived
components:
parameters:
x-year:
name: x-year
in: header
required: false
schema:
type: integer
description: Year of the time range
The current year is the default value.
x-api-key:
name: x-api-key
in: header
required: true
schema:
type: string
description: Unique OpenWeb engagement token
Follow these steps to obtain the engagement token:- From your OpenWeb Admin Dashboard, click Settings.
- Under Authentication Tokens, copy the Engagement value.
NOTE: This value must not be exposed to users.
x-month:
name: x-month
in: header
required: false
schema:
type: integer
minimum: 1
maximum: 12
example: 3
description: 'Number of the month within the `x-year` in which comments were posted
The `x-month` and `x-interval` values determines the duration of comments returned:
- If `x-month` = `3` and `x-interval` = `one-month`, the API returns comments posted in March (month 3 of the year).
- If `x-month` = `3` and `x-interval` = `two-months` (default), the API returns comments posted in March (month 3 of the year) and February (the previous month).
**Default Value**: The month number of the current month.
'
x-interval:
name: x-interval
in: header
required: false
schema:
type: string
enum:
- one-week
- two-weeks
- one-month
- two-months
default: two-months
description: Period of time to return comments
x-weeks:
name: x-weeks
in: header
required: false
schema:
type: string
description: 'Number of the week within the `x-month` of the `x-year` in which comments were posted
The `x-weeks` and `x-interval` values determine the duration of comments returned:
- If `x-weeks` = `3` and `x-interval` = `one-week`, the API returns comments posted in week 3 of the month of the year.
- If `x-weeks` = `3,4` and `x-interval` = `two-weeks`, the API returns comments posted in weeks 3 and 4 of the month of the year.
**NOTES**:
- If `x-interval` = `two-weeks`, the `x-weeks` value must be defined as two consecutive weeks separated by a comma, `3,4`.
- If `x-interval` = `one-month` or `two-months`, the `x-weeks` value is ignored.
'
x-conversation-id:
name: x-conversation-id
in: header
required: true
schema:
type: string
description: 'Unique identifier for the Conversation or thread
Use one of these approaches to obtain this value:
Article Card
1. From your OpenWeb Admin Panel, click **Moderation > Articles**.
2. Search for a comment associated with the Conversation.
3. On the comment card, click **More > Copy conversation ID to clipboard**.
Code
1. Locate the spot ID. Contact your OpenWeb representative if you do not know this value.
2. Identify the post ID. This is the unique article identifier assigned to the article page when it is created.
3. Concatenate the spot ID and postID with an underscore
```
spotID_postID
```
Comment Card
1. From your OpenWeb Admin Panel, click **Moderation > Comments**.
2. Search for a comment associated with the Conversation.
3. On the comment card, click **More > Copy conversation ID to clipboard**.
**NOTE**: Only one of the `x-post-id` or `x-conversation-id` is required. If both values are included in the header, `x-post-id` will be used and `x-conversation-id` will be ignored.'
x-user-id:
name: x-user-id
in: header
required: true
schema:
type: string
description: ID for the user who wrote the comments
x-count:
name: x-count
in: header
required: false
schema:
type: integer
default: 10
description: Number of comments to return
x-spot-id:
name: x-spot-id
in: header
required: true
schema:
type: string
description: Spot ID of the partner
x-post-id:
name: x-post-id
in: header
required: true
schema:
type: string
description: 'Unique article identifier that is specific to the article page
The ideal post ID has the following characteristics:
- Aligns with the URL slug (`an-article-title`) or article ID (`14325`)
- Is **less than 50 characters**, ideally 15 characters
- Uses a combination of letters, numbers, dashes (-), or hyphens (_)
- Except for the regex `[^\w\s\-\:\.\$\~]`, does not include special characters
**NOTE**: Only one of the `x-post-id` or `x-conversation-id` is required. If both values are included in the header, `x-post-id` will be used and `x-conversation-id` will be ignored.
'
responses:
CommentObject:
description: Example response
content:
application/json:
schema:
type: object
x-examples:
Example 1:
comments:
- spot_id: SPOT_ID
post_id: POST_ID
article_name: ARTICLE_NAME
article_url: ARTICLE_URL
article_img: ARTICLE_IMG_URL
conversation_id: SPOT_ID_POST_ID
user_id: USER_ID
username: USERNAME
message_id: SPOT_ID_POST_ID_c_2dxlD797mA4wuiNLcJgDg9mAnIC
content:
- id: ANIMATION_ID
originalHeight: 225
originalUrl: https://media4.giphy.com/media/ANIMATION_ID/giphy.gif
originalWidth: 250
previewHeight: 63
previewUrl: https://media4.giphy.com/media/ANIMATION_ID/giphy-preview.gif
previewWidth: 70
title: ANIMATION_TITLE
type: animation
- id: 160b1173579f25064410a57bd814e176
text: As far as I can see, the company has not yet made any profits.
type: text
message_timestamp: 1710957487
message_type: comment
is_featured: false
like_count: 5
dislike_count: 0
replies_count: 0
user_profile_picture: USER_PROFILE_PICTURE_URL
state: approved
label:
ids:
- BEARISH
section: stock
properties:
comments:
type: array
items:
type: object
properties:
article_name:
type: string
description: Title or name of the article
article_url:
type: string
description: URL of the article
article_img:
type: string
description: Image associated with the article
content:
type: array
description: 'Possible properties of the content
Properties returned depend the `content.type`.'
items:
type: object
properties:
description:
type: string
description: Short description of the content
embed:
type: string
description: HTML tag (`