openapi: 3.0.0
info:
  title: LinkedIn Top Content API
  description: |
    Get a LinkedIn Top Content page: the member posts LinkedIn features on a category or topic, the AI summary some topic pages carry, and the topics around the page.

    Each post carries its text, publish date, author, reactions, comments and media.

    **Cross-linking**: every item in `breadcrumbs`, `subtopics`, `related_topics` and `categories` carries a `topic` value. Pass it as the `topic` parameter to request that page.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: LinkedIn Top Content Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `linkedin_top_content`'
          schema:
            type: string
            enum: ["linkedin_top_content"]
        - name: topic
          in: query
          required: true
          description: 'Top Content page to return, the path after `/top-content/` in its LinkedIn URL: a category such as `career`, one of its topics such as `career/resume-tips`, or a topic page such as `career/resume-tips/tips-for-optimizing-your-linkedin-profile`. The `topic` value of an item in `breadcrumbs`, `subtopics`, `related_topics` or `categories` requests that page. A topic LinkedIn has no page for returns an error, and a page with no posts returns its topics with an error.'
          schema:
            type: string
            maxLength: 300
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        topic:
          $ref: '#/components/schemas/Topic'
        breadcrumbs:
          type: array
          items:
            $ref: '#/components/schemas/TopicLink'
          description: "Topics above this page, from its category down"
        ai_summary:
          $ref: '#/components/schemas/AiSummary'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
          description: "Member posts on the page, in LinkedIn's order"
        subtopics:
          type: array
          items:
            $ref: '#/components/schemas/TopicLink'
          description: "Topics one level below this page"
        related_topics:
          type: array
          items:
            $ref: '#/components/schemas/TopicLink'
          description: "Other topics at the same level as this page"
        categories:
          type: array
          items:
            $ref: '#/components/schemas/TopicLink'
          description: "Other Top Content categories"
        error:
          type: string
          description: "Error message for a `topic` LinkedIn has no page for, or a page with no posts"
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "LinkedIn URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: "Search engine used"
        topic:
          type: string
          description: "Top Content page requested"
    Topic:
      type: object
      required: [title, link]
      properties:
        title:
          type: string
          description: "Name of the topic"
        link:
          type: string
          description: "LinkedIn page of the topic"
    TopicLink:
      type: object
      required: [title, topic, link]
      properties:
        title:
          type: string
          description: "Name of the topic"
        topic:
          type: string
          description: "Value of the topic parameter that requests this page"
        link:
          type: string
          description: "LinkedIn page of the topic"
    AiSummary:
      type: object
      required: [summary]
      properties:
        summary:
          type: string
          description: "Summary LinkedIn wrote with AI from the member posts on the topic"
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/Highlight'
          description: "Points the summary lists"
    Highlight:
      type: object
      required: [text]
      properties:
        title:
          type: string
          description: "Lead-in of the point"
        text:
          type: string
          description: "Text of the point"
    Post:
      type: object
      required: [position, id, link, text, date, iso_date, posted_at, author, reactions, comments]
      properties:
        position:
          type: integer
          description: "Position of the post on the page"
        id:
          type: string
          description: "LinkedIn activity id of the post"
        link:
          type: string
          description: "LinkedIn page of the post"
        text:
          type: string
          description: "Text of the post"
        hashtags:
          type: array
          items:
            type: string
          description: "Hashtags in the post text, without the leading `#`"
        mentions:
          type: array
          items:
            $ref: '#/components/schemas/Mention'
          description: "Members, companies, schools and showcase pages the post text mentions"
        content_links:
          type: array
          items:
            $ref: '#/components/schemas/ContentLink'
          description: "Other links in the post text"
        date:
          type: string
          format: date
          description: "Date the post was published, in YYYY-MM-DD format"
        iso_date:
          type: string
          format: date-time
          description: "Time the post was published, in ISO 8601 format"
        posted_at:
          type: string
          description: "How long ago the post was published, as LinkedIn shows it"
        is_edited:
          type: boolean
          description: "Whether LinkedIn marks the post as edited"
        author:
          $ref: '#/components/schemas/Author'
        reactions:
          type: integer
          description: "Number of reactions to the post"
        comments:
          type: integer
          description: "Number of comments on the post"
        images:
          type: array
          items:
            type: string
          description: "Images attached to the post"
        video:
          $ref: '#/components/schemas/Video'
        document:
          $ref: '#/components/schemas/Document'
        article:
          $ref: '#/components/schemas/Article'
    Mention:
      type: object
      required: [name, link]
      properties:
        name:
          type: string
          description: "Name of the mentioned member or page, as the post shows it"
        link:
          type: string
          description: "LinkedIn page of the mentioned member or page"
    ContentLink:
      type: object
      required: [text, link]
      properties:
        text:
          type: string
          description: "Text of the link, as the post shows it"
        link:
          type: string
          description: "Destination of the link"
    Author:
      type: object
      required: [name, link]
      properties:
        name:
          type: string
          description: "Name of the author"
        link:
          type: string
          description: "LinkedIn page of the author"
        headline:
          type: string
          description: "Headline under the author's name"
        thumbnail:
          type: string
          description: "Profile photo of the author"
        followers:
          type: integer
          description: "Number of followers the author has"
        is_influencer:
          type: boolean
          description: "Whether LinkedIn shows its influencer badge beside the author"
    Video:
      type: object
      properties:
        link:
          type: string
          description: "Video file at the highest bitrate LinkedIn offers"
        thumbnail:
          type: string
          description: "Poster image of the video"
    Document:
      type: object
      properties:
        title:
          type: string
          description: "Title of the document"
        pages:
          type: array
          items:
            type: string
          description: "Images of the first pages of the document"
        total_pages:
          type: integer
          description: "Number of pages in the document"
    Article:
      type: object
      properties:
        title:
          type: string
          description: "Title of the shared article"
        source:
          type: string
          description: "Source of the article as LinkedIn shows it"
        link:
          type: string
          description: "Link to the article"
        thumbnail:
          type: string
          description: "Image of the article"
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong