openapi: 3.0.3
info:
  title: Listen API (V2)
  version: 1.0.0
  description: |
    **Rate limiting:**
      • Projects list: 300 requests per hour
      • Search endpoints (full search & recent search): 30 requests per hour (shared)
    
    **Rate limiting headers:**
    All API responses include the following headers:
      • `x-rate-limit-limit`: Limit of requests for particular API endpoint
      • `x-rate-limit-reset`: Unix timestamp (seconds) when limits will reset
      • `x-rate-limit-remaining`: Remaining number of requests
servers:
  - url: https://sentione.com/api/public/v2
  - url: https://{hostname}/api/public/v2
    variables:
      server:
        default: https://sentione.com # SaaS server
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: |
        Your API key for authenticating requests. 
        Obtain or regenerate your key at https://sentione.com/app#/profile/api
  parameters:
    ContentTypeHeader:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        enum: [application/json]
      description: API requests must have the Content-Type set to application/json
  schemas:
    Project:
      type: object
      description: A project within the SentiOne Listen platform
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the project
        name:
          type: string
          description: Human-readable name of the project
      required:
        - id
        - name
    SearchRequest:
      type: object
      description: |
        Request model for searching mentions with optional filters and sorting.
        If `sortType` is omitted, defaults to `PublishedAtDescending`.
      properties:
        filters:
          $ref: '#/components/schemas/Filters'
        sortType:
          $ref: '#/components/schemas/SortType'
    Filters:
      type: object
      description: |
        Filters to apply to the search.
        If omitted in Recent mentions search, `publishedAt` defaults to the last 7 days.
      properties:
        publishedAt:
          $ref: '#/components/schemas/TimeRange'
          description: |
            Time range for filtering by published date (ISO 8601 UTC format, e.g. 2025-05-22T10:30:00Z).
            Defaults to last 7 days in Recent mentions search.
        source:
          $ref: '#/components/schemas/SourceFilters'
          description: Criteria to filter mentions by their source
        type:
          type: array
          items:
            $ref: '#/components/schemas/MentionType'
          description: List of mention types to include (e.g., Post, Comment)
        content:
          $ref: '#/components/schemas/MentionContentFilters'
          description: Filters related to the content of mentions (e.g., sentiment)
    SortType:
      type: string
      description: Defines how to sort search results (Default is PublishedAtDescending)
      enum:
        - PublishedAtDescending
        - PublishedAtAscending
        - CollectedAtDescending
        - CollectedAtAscending
        - InfluenceScoreDescending
        - EngagementRateDescending
        - LikeCountDescending
        - ShareCountDescending
        - FollowerCountDescending
    TimeRange:
      type: object
      description: |
        Range of dates to filter mentions by, specified in ISO 8601 format and UTC timezone (e.g. 2025-05-22T10:30:00Z).
      properties:
        from:
          type: string
          format: date-time
          description: Start datetime of the range (inclusive) - ISO8601 format (e.g. 2025-05-20T00:00:00Z)
        to:
          type: string
          format: date-time
          description: End datetime of the range (exclusive) - ISO8601 format (e.g. 2025-05-22T23:59:59Z)
    MentionContentFilters:
      type: object
      description: Filters specific to the content attributes of mentions
      properties:
        sentiment:
          type: array
          items:
            $ref: '#/components/schemas/Sentiment'
          description: List of sentiments to include (e.g. Positive, Negative)
    SourceFilters:
      type: object
      description: Filters for the source platforms/sites of mentions
      properties:
        type:
          type: array
          items:
            $ref: '#/components/schemas/SourceType'
          description: List of source types to include (e.g. Facebook, Reddit)
    MentionType:
      type: string
      description: Enumeration of possible mention formats
      enum:
        - Post
        - Comment
        - Article
        - PrivateMessage
        - Share
    SourceType:
      type: string
      description: Enumeration of platforms or channels where mentions originate
      enum:
        - Facebook
        - Websites
        - Instagram
        - Forums
        - X
        - Blogs
        - TikTok
        - Reviews
        - Reddit
        - Video
        - Imported
        - Other
    Sentiment:
      type: string
      description: Sentiment classification of mention content
      enum:
        - Positive
        - Negative
        - Neutral
        - Unspecified
    Language:
      type: object
      description: Language details
      properties:
        code:
          type: string
          description: ISO 639-1 language code
      required:
        - code
    MentionContent:
      type: object
      description: Detailed content of the mention
      properties:
        text:
          type: string
          nullable: true
          description: Text body of the mention. (Optional)
        language:
          $ref: '#/components/schemas/Language'
          nullable: true
          description: Language of the mention content
        sentiment:
          $ref: '#/components/schemas/Sentiment'
          description: Sentiment classification of the mention
      required:
        - sentiment
    EngagementMetrics:
      type: object
      description: Summary of overall and per-source engagement metrics
      properties:
        influenceScore:
          type: integer
          nullable: true
          description: Influence score (1 - 10)
        engagementRate:
          type: number
          format: double
          nullable: true
          description: Rate of engagement relative to exposure
        sourceMetrics:
          $ref: '#/components/schemas/SourceEngagementMetrics'
          description: Source-specific breakdown of engagement metrics
      required:
        - sourceMetrics
    SourceEngagementMetrics:
      type: object
      description: Engagement metrics broken down by individual sources
      properties:
        common:
          $ref: '#/components/schemas/GenericSourceEngagementMetrics'
          description: Common engagement metrics across all sources
        facebook:
          $ref: '#/components/schemas/FacebookSourceEngagementMetrics'
          nullable: true
          description: Facebook-specific reaction counts
        newsAggregators:
          $ref: '#/components/schemas/NewsAggregatorSourceEngagementMetrics'
          nullable: true
          description: Counts of interactions on news aggregator platforms
        twitter:
          $ref: '#/components/schemas/TwitterSourceEngagementMetrics'
          nullable: true
          description: Twitter-specific engagement counts
      required:
        - common
    GenericSourceEngagementMetrics:
      type: object
      description: Common engagement metrics for a mention
      properties:
        likeCount:
          type: integer
          format: int64
          nullable: true
          description: Number of likes; optional
        shareCount:
          type: integer
          format: int64
          nullable: true
          description: Number of shares; optional
        commentCount:
          type: integer
          format: int64
          nullable: true
          description: Number of comments; optional
        viewCount:
          type: integer
          format: int64
          nullable: true
          description: Number of views; optional
    FacebookSourceEngagementMetrics:
      type: object
      description: Reaction counts specific to Facebook
      properties:
        likeCount:
          type: integer
          format: int64
          description: Number of likes
        loveCount:
          type: integer
          format: int64
          description: Number of 'Love' reactions
        hahaCount:
          type: integer
          format: int64
          description: Number of 'Haha' reactions
        wowCount:
          type: integer
          format: int64
          description: Number of 'Wow' reactions
        sadCount:
          type: integer
          format: int64
          description: Number of 'Sad' reactions
        angryCount:
          type: integer
          format: int64
          description: Number of 'Angry' reactions
      required:
        - likeCount
        - loveCount
        - hahaCount
        - wowCount
        - sadCount
        - angryCount
    NewsAggregatorSourceEngagementMetrics:
      type: object
      description: Engagement metrics for news aggregator platforms
      properties:
        digsCount:
          type: integer
          format: int64
          description: Number of 'Digs' on aggregator sites
        burrowsCount:
          type: integer
          format: int64
          description: Number of 'Burrows' on aggregator sites
      required:
        - digsCount
        - burrowsCount
    TwitterSourceEngagementMetrics:
      type: object
      description: Engagement metrics for Twitter
      properties:
        retweetsCount:
          type: integer
          format: int64
          description: Number of retweets
        favouritesCount:
          type: integer
          format: int64
          description: Number of favourites
      required:
        - retweetsCount
        - favouritesCount
    CursorPageResponse_Project:
      type: object
      description: Paginated response for listing projects
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Project'
          description: Array of projects on the current page
        cursor:
          type: string
          description: Cursor token for next page, or null if this is the last page
      required:
        - data
    CursorPageResponse_Mention:
      type: object
      description: Paginated response for mentions search
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Mention'
          description: Array of mentions on the current page
        cursor:
          type: string
          description: Cursor token for next page, or null if this is the last page
      required:
        - data
    ErrorResponse:
      type: object
      description: Generic error response
      properties:
        message:
          type: string
          description: Error message describing what went wrong
      required:
        - message
    ValidationErrorResponse:
      type: object
      description: Error response for invalid request fields
      properties:
        message:
          type: string
          description: General validation error message
        requestFieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Mapping of field names to lists of validation error messages
      required:
        - message
        - requestFieldErrors
    Coordinates:
      type: object
      description: Geographic coordinates
      properties:
        latitude:
          type: number
          format: double
          description: Latitude coordinate
        longitude:
          type: number
          format: double
          description: Longitude coordinate
      required:
        - latitude
        - longitude
    Country:
      type: object
      description: Country information
      properties:
        code:
          type: string
          description: Country code
      required:
        - code
    Location:
      type: object
      description: Geographical location details of the mention
      properties:
        coordinates:
          $ref: '#/components/schemas/Coordinates'
          nullable: true
          description: Geographic coordinates if available
        country:
          $ref: '#/components/schemas/Country'
          nullable: true
          description: Country information if available
        region:
          type: string
          nullable: true
          description: Region or state name
        city:
          type: string
          nullable: true
          description: City name
    SocialChannel:
      type: object
      description: Information about a social media channel (eg. FB Fanpage, YouTube Channel, IG Profile) the mention is coming from.
      properties:
        id:
          type: string
          nullable: true
          description: Unique identifier of the social channel
        name:
          type: string
          nullable: true
          description: Name of the social channel
    Source:
      type: object
      description: Metadata about the source of a mention
      properties:
        socialChannel:
          $ref: '#/components/schemas/SocialChannel'
          description: Information about the source social channel
        mentionUrl:
          type: string
          description: URL to the original mention
        type:
          $ref: '#/components/schemas/SourceType'
          description: Type of source platform
      required:
        - socialChannel
        - mentionUrl
        - type
    AuthorGender:
      type: string
      description: Gender of the author
      enum:
        - Male
        - Female
        - Unspecified
    AuthorInfluenceMetrics:
      type: object
      description: Metrics related to author's influence
      properties:
        followerCount:
          type: integer
          format: int64
          nullable: true
          description: Number of followers
        fanCount:
          type: integer
          format: int64
          nullable: true
          description: Number of fans
    Author:
      type: object
      description: Information about the author of a mention
      properties:
        id:
          type: string
          nullable: true
          description: Unique identifier of the author
        name:
          type: string
          nullable: true
          description: Display name of the author
        avatar:
          $ref: '#/components/schemas/Attachment'
          nullable: true
          description: Author's avatar image
        gender:
          $ref: '#/components/schemas/AuthorGender'
          description: Gender of the author
        influenceMetrics:
          $ref: '#/components/schemas/AuthorInfluenceMetrics'
          description: Metrics related to author's influence
      required:
        - gender
        - influenceMetrics
    AttachmentType:
      type: string
      description: Type of attachment
      enum:
        - Image
        - Video
        - Other
    Attachment:
      type: object
      description: Details of a single attachment associated with a mention
      properties:
        url:
          type: string
          description: URL to the attachment
        type:
          $ref: '#/components/schemas/AttachmentType'
          description: Type of attachment
      required:
        - url
        - type
    Mention:
      type: object
      description: Structure representing a single mention
      properties:
        id:
          type: string
          description: Unique identifier of the mention
        author:
          $ref: '#/components/schemas/Author'
          description: Information about the mention's author
        source:
          $ref: '#/components/schemas/Source'
          description: Source platform or site of the mention
        type:
          $ref: '#/components/schemas/MentionType'
          description: The mention type (Post, Comment, Article, PrivateMessage, Share)
        publishedAt:
          type: string
          format: date-time
          description: Timestamp when the mention was published (ISO 8601 UTC format, e.g. 2025-05-22T14:30:00Z)
        collectedAt:
          type: string
          format: date-time
          description: Timestamp when the mention was collected by SentiOne Listen crawlers (ISO 8601 UTC format, e.g. 2025-05-22T15:45:00Z)
        content:
          $ref: '#/components/schemas/MentionContent'
          description: Detailed content of the mention
        engagementMetrics:
          $ref: '#/components/schemas/EngagementMetrics'
          description: Metrics related to engagement (likes, shares, comments, etc.)
        location:
          $ref: '#/components/schemas/Location'
          description: Geolocation metadata if available
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: List of attachments (images, files) associated with the mention
      required:
        - id
        - author
        - source
        - type
        - publishedAt
        - collectedAt
        - content
        - engagementMetrics
        - attachments
paths:
  /projects:
    get:
      summary: List all projects
      operationId: listProjectsV2
      tags:
        - Projects
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ContentTypeHeader'
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination
      description: |-
        **Tier**: Basic
        **Rate limit**: 300 requests per hour
      responses:
        '200':
          description: A paginated list of projects
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 300
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 287
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPageResponse_Project'
              examples:
                project_list:
                  summary: Example projects list
                  value:
                    data:
                      - id: 12345
                        name: "Brand Monitoring Campaign"
                      - id: 67890
                        name: "Competitor Analysis Q2"
                    cursor: "eyJwYWdlIjoyLCJsaW1pdCI6MjV9"
        '401':
          description: Authentication errors
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 300
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 287
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key_format:
                  summary: Invalid API key format
                  value:
                    message: "Invalid format of the API key provided. It should start with prefix: S1-APIKEY- You can find your API key by navigating into https://sentione.com/app#/profile/api"
                invalid_api_key:
                  summary: Invalid API key
                  value:
                    message: "Invalid API Key supplied in X-API-KEY header"
                missing_api_key:
                  summary: Missing API key
                  value:
                    message: "API Key was not supplied in X-API-KEY header"
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    message: "Insufficient permissions to access this endpoint"
        '415':
          description: Unsupported media type
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 300
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 287
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported_media_type:
                  summary: Missing or invalid Content-Type header
                  value:
                    message: "Unsupported media type for this endpoint. Please add valid Content-Type header to the reuqest eg. Content-Type: application/json"
        '429':
          description: Rate limit exceeded (max 300 requests per hour)
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 300
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit_exceeded:
                  summary: Rate limit exceeded for projects endpoint
                  value:
                    message: "Rate limit of requests for this endpoint has been reached. Maximum number of requests for this endpoint is 300. Limits will reset at 2025-05-22T15:00:00Z."
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /projects/{projectId}/mentions/recent/search:
    post:
      summary: Recent mentions search
      description: |-
        **Tier**: Basic
        **Rate limit**: 30 requests per hour
        **Data limitations:** Mentions published within last 7 days only

        Allows to extract 25 **recent** mentions (published within last 7 days) from selected project per request.
        Multiple different filters such as time-range, sentiment, source can be applied.
      operationId: recentSearchMentionsV2
      tags:
        - Mentions
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ContentTypeHeader'
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination of search results
      requestBody:
        required: true
        description: Even if no filters or sorting options are provided, an empty JSON object (`{}`) must be sent in the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              empty:
                summary: Empty request (no filters, uses defaults)
                description: Returns all mentions from the last 7 days, sorted by published date descending
                value: {}
              basic_sentiment_filter:
                summary: Filter by positive sentiment only
                description: Get only positive mentions from the last 7 days
                value:
                  filters:
                    content:
                      sentiment: ["Positive"]
              social_media_only:
                summary: Social media platforms only
                description: Filter mentions from Facebook, Instagram, and X only
                value:
                  filters:
                    source:
                      type: ["Facebook", "Instagram", "X"]
              posts_and_comments:
                summary: Filter by mention type
                description: Get only posts and comments, excluding articles and other types
                value:
                  filters:
                    type: ["Post", "Comment"]
              custom_date_range:
                summary: Custom date range within last 7 days
                description: Get mentions from a specific time period (must be within last 7 days for recent search)
                value:
                  filters:
                    publishedAt:
                      from: "2025-05-20T00:00:00Z"
                      to: "2025-05-22T23:59:59Z"
              complex_filter:
                summary: Complex multi-filter search
                description: Combine multiple filters - negative sentiment from Reddit and Forums, sorted by engagement
                value:
                  filters:
                    content:
                      sentiment: ["Negative"]
                    source:
                      type: ["Reddit", "Forums"]
                    type: ["Post", "Comment"]
                  sortType: "EngagementRateDescending"
              high_engagement:
                summary: Sort by number of likes
                description: Get mentions sorted by number of likes metric
                value:
                  sortType: "LikeCountDescending"
      responses:
        '200':
          description: Paginated recent search results of mentions (last 7 days)
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPageResponse_Mention'
              examples:
                social_media_mentions:
                  summary: Example social media mentions from recent search
                  value:
                    data:
                      - id: "smid-wcuEd-YCoP89RC676Z97taQ2Nk97_T5HYBbFSb1rwOCzvdVLUm5GMI6tZXFUhoU5v0zQiWgt48ZllN5iXPF9tVuU4dFDR0COkaoLAVFOrYCbXju8Nztir6cPSOMdITnpMZMjNsALWcK3MU1tevSnNpZojdQD2IzBQfzYx_o"
                        author:
                          id: "facebook_user_1234567890"
                          name: "Sarah Johnson"
                          avatar:
                            url: "https://cdn.facebook.com/avatars/user_1234567890.jpg"
                            type: "Image"
                          gender: "Female"
                          influenceMetrics:
                            followerCount: 245
                            fanCount: null
                        source:
                          socialChannel:
                            id: "facebook_page_987654321"
                            name: "Tech Reviews Hub"
                          mentionUrl: "https://www.facebook.com/posts/123456789012345"
                          type: "Facebook"
                        type: "Post"
                        publishedAt: "2025-05-22T10:30:00Z"
                        collectedAt: "2025-05-22T10:32:15Z"
                        content:
                          text: "Just tried the new smartphone and I'm really impressed! The camera quality is amazing and battery life exceeds expectations. Definitely recommend it to anyone looking for an upgrade."
                          language:
                            code: "en"
                          sentiment: "Positive"
                        engagementMetrics:
                          influenceScore: 7
                          engagementRate: 0.125
                          sourceMetrics:
                            common:
                              likeCount: 28
                              shareCount: 3
                              commentCount: 12
                              viewCount: null
                            facebook:
                              likeCount: 28
                              loveCount: 8
                              hahaCount: 0
                              wowCount: 2
                              sadCount: 0
                              angryCount: 0
                            newsAggregators: null
                            twitter: null
                        location:
                          coordinates: null
                          country:
                            code: "US"
                          region: "California"
                          city: "San Francisco"
                        attachments:
                          - url: "https://cdn.facebook.com/photos/smartphone_review_image.jpg"
                            type: "Image"
                      - id: "smid-xTrP3-QnVm45AB123X98cdP7hE23_M4KaLmNcOp2vwXQrsDfG8JkT9eR5zIwFbCr6u1sLpYn3HvKjM8oVzA9bE2fZqRtUc7PgNl4iWkY3hXm6DfJsRtPq9aIv2bGtU5eNmK8cH3rF9wJxL4pYq6"
                        author:
                          id: "instagram_user_9876543210"
                          name: "TechGuru_Mike"
                          avatar:
                            url: "https://instagram.cdninstagram.com/profiles/user_9876543210.jpg"
                            type: "Image"
                          gender: "Male"
                          influenceMetrics:
                            followerCount: 15420
                            fanCount: null
                        source:
                          socialChannel:
                            id: "instagram_profile_456789123"
                            name: "TechGuru_Mike"
                          mentionUrl: "https://www.instagram.com/p/CqR3St8vN9M/"
                          type: "Instagram"
                        type: "Comment"
                        publishedAt: "2025-05-21T16:45:30Z"
                        collectedAt: "2025-05-21T16:47:22Z"
                        content:
                          text: "Great review! I've been considering this model too. How's the low-light camera performance? 📸"
                          language:
                            code: "en"
                          sentiment: "Neutral"
                        engagementMetrics:
                          influenceScore: 8
                          engagementRate: 0.089
                          sourceMetrics:
                            common:
                              likeCount: 15
                              shareCount: 0
                              commentCount: 3
                              viewCount: null
                            facebook: null
                            newsAggregators: null
                            twitter: null
                        location:
                          coordinates:
                            latitude: 40.7128
                            longitude: -74.0060
                          country:
                            code: "US"
                          region: "New York"
                          city: "New York"
                        attachments: []
                    cursor: "eyJwYWdlIjoyLCJsaW1pdCI6MjUsInRpbWVzdGFtcCI6IjIwMjUtMDUtMjFUMTY6NDU6MzBaIn0="
        '400':
          description: Bad request - invalid request format
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_request_format:
                  summary: Request fields not in expected format
                  value:
                    message: "Request fields were not in expected format"
        '401':
          description: Authentication errors
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key_format:
                  summary: Invalid API key format
                  value:
                    message: "Invalid format of the API key provided. It should start with prefix: S1-APIKEY- You can find your API key by navigating into https://sentione.com/app#/profile/api"
                invalid_api_key:
                  summary: Invalid API key
                  value:
                    message: "Invalid API Key supplied in X-API-KEY header"
                missing_api_key:
                  summary: Missing API key
                  value:
                    message: "API Key was not supplied in X-API-KEY header"
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    message: "Insufficient permissions to access this endpoint"
        '415':
          description: Unsupported media type
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported_media_type:
                  summary: Missing or invalid Content-Type header
                  value:
                    message: "Unsupported media type for this endpoint. Please add valid Content-Type header to the reuqest eg. Content-Type: application/json"
        '422':
          description: Validation error - request values not allowed
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                invalid_filter_values:
                  summary: Request values are not allowed
                  value:
                    message: "Request values are not allowed"
                    requestFieldErrors:
                      "filters.publishedAt.from": ["Date must be within last 7 days for recent search"]
                      "filters.source.type": ["InvalidSourceType is not a valid source type"]
        '429':
          description: Rate limit exceeded (max 30 requests per hour shared)
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit_exceeded:
                  summary: Rate limit exceeded for search endpoints
                  value:
                    message: "Rate limit of requests for this endpoint has been reached. Maximum number of requests for this endpoint is 30. Limits will reset at 2025-05-22T16:00:00Z."
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /projects/{projectId}/mentions/search:
    post:
      summary: Historical search
      description: |-
        **Tier**: Enterprise
        **Rate limit**: 30 requests per hour
        **Data limitations:** None

        Allows to extract 25 mentions from selected project per request.
        Multiple different filters such as time-range, sentiment, source can be applied.
      operationId: searchMentionsV2
      tags:
        - Mentions
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ContentTypeHeader'
        - name: projectId
          in: path
          required: true
          schema:
            type: integer
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination of search results
      requestBody:
        required: true
        description: Even if no filters or sorting options are provided, an empty JSON object (`{}`) must be sent in the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              empty:
                summary: Empty request (no filters)
                description: Returns all historical mentions, sorted by published date descending
                value: {}
              last_month:
                summary: Mentions from April 2025
                description: Get all mentions from April
                value:
                  filters:
                    publishedAt:
                      from: "2025-04-01T00:00:00Z"
                      to: "2025-05-01T00:00:00Z"
              quarterly_analysis:
                summary: Quarterly sentiment analysis
                description: Get all mentions from Q1 2025 for sentiment analysis
                value:
                  filters:
                    publishedAt:
                      from: "2025-01-01T00:00:00Z"
                      to: "2025-03-31T23:59:59Z"
                    content:
                      sentiment: ["Positive", "Negative", "Neutral"]
                  sortType: "PublishedAtAscending"
              news_and_blogs:
                summary: News and blog coverage
                description: Focus on editorial content from websites and blogs
                value:
                  filters:
                    source:
                      type: ["Websites", "Blogs"]
                    type: ["Article"]
                  sortType: "InfluenceScoreDescending"
              viral_content:
                summary: High-engagement content
                description: Find viral mentions with high engagement, sorted by share count
                value:
                  filters:
                    publishedAt:
                      from: "2025-01-01T00:00:00Z"
                      to: "2025-05-22T23:59:59Z"
                  sortType: "ShareCountDescending"
              crisis_monitoring:
                summary: Crisis monitoring setup
                description: Monitor negative sentiment across all platforms for crisis management
                value:
                  filters:
                    content:
                      sentiment: ["Negative"]
                    publishedAt:
                      from: "2025-05-01T00:00:00Z"
                      to: "2025-05-22T23:59:59Z"
                  sortType: "InfluenceScoreDescending"
              competitor_analysis:
                summary: Multi-platform competitor analysis
                description: Comprehensive analysis across social media and review platforms
                value:
                  filters:
                    source:
                      type: ["Facebook", "X", "Instagram", "Reviews", "Reddit"]
                    type: ["Post", "Comment"]
                    publishedAt:
                      from: "2025-04-01T00:00:00Z"
                      to: "2025-05-22T23:59:59Z"
                  sortType: "EngagementRateDescending"
              influencer_content:
                summary: High-influence content
                description: Focus on content from high-influence authors
                value:
                  filters:
                    publishedAt:
                      from: "2025-03-01T00:00:00Z"
                      to: "2025-05-22T23:59:59Z"
                  sortType: "FollowerCountDescending"
      responses:
        '200':
          description: Paginated search results of mentions
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPageResponse_Mention'
              examples:
                historical_mentions:
                  summary: Example historical mentions with Twitter and Facebook content
                  value:
                    data:
                      - id: "smid-hTvQ8-ZnPo12CD456Y89efR9kF45_N6LcNpQdRs4xyYTueDgH9KmU0fS7wJzGcDs8v2tMqZo5IxLkO9pWaB0cF3gZrUd8QgNm2iXl7vYq5"
                        author:
                          id: "twitter_user_5647382910"
                          name: "Alex_TechReviewer"
                          avatar:
                            url: "https://pbs.twimg.com/profile_images/user_5647382910.jpg"
                            type: "Image"
                          gender: "Male"
                          influenceMetrics:
                            followerCount: 8750
                            fanCount: null
                        source:
                          socialChannel:
                            id: "twitter_profile_5647382910"
                            name: "Alex_TechReviewer"
                          mentionUrl: "https://twitter.com/Alex_TechReviewer/status/1793842756394827562"
                          type: "X"
                        type: "Post"
                        publishedAt: "2025-04-15T09:22:15Z"
                        collectedAt: "2025-04-15T09:24:33Z"
                        content:
                          text: "After 3 months with this device, I can confidently say it's changed my workflow completely. The performance is consistently excellent and customer support has been outstanding. Worth every penny! #TechReview #ProductReview"
                          language:
                            code: "en"
                          sentiment: "Positive"
                        engagementMetrics:
                          influenceScore: 8
                          engagementRate: 0.152
                          sourceMetrics:
                            common:
                              likeCount: 47
                              shareCount: 12
                              commentCount: 8
                              viewCount: 2340
                            facebook: null
                            newsAggregators: null
                            twitter:
                              retweetsCount: 12
                              favouritesCount: 47
                        location:
                          coordinates: null
                          country:
                            code: "CA"
                          region: "Ontario"
                          city: "Toronto"
                        attachments: []
                      - id: "smid-rYqE4-MnBx67GH890Z12fgS3lH67_P8NdQrTeSu6yzZVwfEiI1LnV2hU9xKaHdFt0w4uOrAp7JyMlR1qXcC2dG5hAtVe0ShQo6jYm9wAz2k"
                        author:
                          id: "facebook_user_3456789012"
                          name: "Jennifer Martinez"
                          avatar:
                            url: "https://cdn.facebook.com/avatars/user_3456789012.jpg"
                            type: "Image"
                          gender: "Female"
                          influenceMetrics:
                            followerCount: 892
                            fanCount: null
                        source:
                          socialChannel:
                            id: "facebook_group_147258369"
                            name: "Tech Enthusiasts Community"
                          mentionUrl: "https://www.facebook.com/groups/techcommunity/posts/456789123456789"
                          type: "Facebook"
                        type: "Comment"
                        publishedAt: "2025-03-28T14:17:42Z"
                        collectedAt: "2025-03-28T14:19:08Z"
                        content:
                          text: "I had some issues with mine initially, but after the latest software update everything works perfectly. Customer service was really helpful in resolving the problems. Overall satisfied with the purchase now."
                          language:
                            code: "en"
                          sentiment: "Neutral"
                        engagementMetrics:
                          influenceScore: 5
                          engagementRate: 0.067
                          sourceMetrics:
                            common:
                              likeCount: 23
                              shareCount: 1
                              commentCount: 6
                              viewCount: null
                            facebook:
                              likeCount: 23
                              loveCount: 3
                              hahaCount: 0
                              wowCount: 0
                              sadCount: 1
                              angryCount: 0
                            newsAggregators: null
                            twitter: null
                        location:
                          coordinates:
                            latitude: 25.7617
                            longitude: -80.1918
                          country:
                            code: "US"
                          region: "Florida"
                          city: "Miami"
                        attachments:
                          - url: "https://cdn.facebook.com/photos/product_screenshot_example.jpg"
                            type: "Image"
                    cursor: "eyJwYWdlIjoyLCJsaW1pdCI6MjUsInRpbWVzdGFtcCI6IjIwMjUtMDMtMjhUMTQ6MTc6NDJaIiwiaGlzdG9yaWNhbCI6dHJ1ZX0="
        '400':
          description: Bad request - invalid request format
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_request_format:
                  summary: Request fields not in expected format
                  value:
                    message: "Request fields were not in expected format"
        '401':
          description: Authentication errors
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key_format:
                  summary: Invalid API key format
                  value:
                    message: "Invalid format of the API key provided. It should start with prefix: S1-APIKEY- You can find your API key by navigating into https://sentione.com/app#/profile/api"
                invalid_api_key:
                  summary: Invalid API key
                  value:
                    message: "Invalid API Key supplied in X-API-KEY header"
                missing_api_key:
                  summary: Missing API key
                  value:
                    message: "API Key was not supplied in X-API-KEY header"
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    message: "Insufficient permissions to access this endpoint"
        '415':
          description: Unsupported media type
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported_media_type:
                  summary: Missing or invalid Content-Type header
                  value:
                    message: "Unsupported media type for this endpoint. Please add valid Content-Type header to the reuqest eg. Content-Type: application/json"
        '422':
          description: Validation error - request values not allowed
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 18
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                invalid_filter_values:
                  summary: Request values are not allowed
                  value:
                    message: "Request values are not allowed"
                    requestFieldErrors:
                      "filters.publishedAt.from": ["Date cannot be in the future"]
                      "filters.content.sentiment": ["InvalidSentiment is not a valid sentiment type"]
        '429':
          description: Rate limit exceeded (max 30 requests per hour shared)
          headers:
            x-rate-limit-limit:
              description: Limit of requests for particular API endpoint
              schema:
                type: integer
                example: 30
            x-rate-limit-reset:
              description: Unix timestamp (seconds) when limits will reset
              schema:
                type: integer
                example: 1747666800
            x-rate-limit-remaining:
              description: Remaining number of requests
              schema:
                type: integer
                example: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit_exceeded:
                  summary: Rate limit exceeded for search endpoints
                  value:
                    message: "Rate limit of requests for this endpoint has been reached. Maximum number of requests for this endpoint is 30. Limits will reset at 2025-05-22T16:00:00Z."
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
security:
  - ApiKeyAuth: []