SocialListeningAPI

SocialListeningAPI Hacker News API

Hacker News API endpoints.

Documentation GitHub OpenAPI

Business capability

Web Data AE-230.40

Operations 2

GET /api/v1/hackernews/search Search Hacker News posts #

POST /api/v1/hackernews/search Search Hacker News posts #

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/sociallisteningapi:sociallisteningapi-hacker-news-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. See our Privacy Policy and Terms.

GitHub Google LinkedIn

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

OpenAPI Specification

openapi: 3.2.0
info:
  title: SocialListening Hackernews API
  version: 1.0.0
  description: Search and retrieve public social data through one normalized API.
  x-updated-at: '2026-09-23T00:00:00.000Z'
servers:
- url: https://api.sociallisteningapi.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Hacker News
  description: Hacker News API endpoints.
  x-display-name: Hacker News
  x-logo: /hn.svg
paths:
  /api/v1/hackernews/search:
    get:
      operationId: searchHackernews
      tags:
      - Hacker News
      summary: Search Hacker News posts
      description: Search Hacker News stories and comments by keyword, newest first, and return normalized content, engagement, and source data.
      x-credit-cost: 1
      responses:
        '200':
          description: Request completed successfully.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialSearchResponse'
              example:
                success: true
                platform: hackernews
                endpoint: /api/v1/hackernews/search
                data:
                  items:
                  - id: '41234567'
                    platform: hackernews
                    url: https://news.ycombinator.com/item?id=41234567
                    content:
                      title: 'Show HN: A social listening API'
                      text: A practical guide to social listening for small teams.
                      media_urls: []
                      thumbnail_url: null
                    author:
                      id: alex
                      username: alex
                      display_name: alex
                      avatar_url: null
                      verified: null
                    engagement:
                      views: 1200
                      likes: 48
                      comments: 7
                      shares: 3
                      saves: null
                    published_at: '2026-08-05T01:30:00.000Z'
                    ext:
                      story_id: '41234567'
                pagination:
                  next_cursor: null
                  has_more: false
                  page_size: 1
                raw:
                  hits: []
                request_id: req_example123
                credits_used: 1
                credits_remaining: 99
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/WorkspaceNotActivated'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/UpstreamProviderError'
      parameters:
      - name: query
        in: query
        required: true
        description: The keyword or phrase to search for.
        schema:
          type: string
          minLength: 1
        example: social listening
      - name: cursor
        in: query
        required: false
        description: The cursor returned by the previous response.
        schema:
          type: string
          minLength: 1
          pattern: ^[1-9][0-9]*$
        example: '1'
      - name: raw
        in: query
        required: false
        description: Include the unchanged provider response in the raw field. Defaults to false.
        schema:
          type: boolean
          default: false
        example: true
    post:
      operationId: searchHackernewsWithPost
      tags:
      - Hacker News
      summary: Search Hacker News posts
      description: Search Hacker News stories and comments by keyword, newest first, and return normalized content, engagement, and source data.
      x-credit-cost: 1
      responses:
        '200':
          description: Request completed successfully.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialSearchResponse'
              example:
                success: true
                platform: hackernews
                endpoint: /api/v1/hackernews/search
                data:
                  items:
                  - id: '41234567'
                    platform: hackernews
                    url: https://news.ycombinator.com/item?id=41234567
                    content:
                      title: 'Show HN: A social listening API'
                      text: A practical guide to social listening for small teams.
                      media_urls: []
                      thumbnail_url: null
                    author:
                      id: alex
                      username: alex
                      display_name: alex
                      avatar_url: null
                      verified: null
                    engagement:
                      views: 1200
                      likes: 48
                      comments: 7
                      shares: 3
                      saves: null
                    published_at: '2026-08-05T01:30:00.000Z'
                    ext:
                      story_id: '41234567'
                pagination:
                  next_cursor: null
                  has_more: false
                  page_size: 1
                raw:
                  hits: []
                request_id: req_example123
                credits_used: 1
                credits_remaining: 99
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/WorkspaceNotActivated'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/UpstreamProviderError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  minLength: 1
                  description: The keyword or phrase to search for.
                cursor:
                  type: string
                  minLength: 1
                  pattern: ^[1-9][0-9]*$
                  description: The cursor returned by the previous response.
                raw:
                  type: boolean
                  default: false
                  description: Include the unchanged provider response in the raw field. Defaults to false.
              additionalProperties: false
            example:
              query: social listening
              cursor: '1'
              raw: true
components:
  headers:
    RateLimitReset:
      description: The Unix timestamp when the current rate-limit window resets.
      schema:
        type: integer
    RequestId:
      description: The unique ID assigned to the request.
      schema:
        type: string
    RateLimitLimit:
      description: The maximum requests allowed in the current minute.
      schema:
        type: integer
    RateLimitRemaining:
      description: The requests remaining in the current minute.
      schema:
        type: integer
    RetryAfter:
      description: The seconds until another request can be attempted.
      schema:
        type: integer
  schemas:
    Pagination:
      type: object
      required:
      - next_cursor
      - has_more
      - page_size
      properties:
        next_cursor:
          type:
          - string
          - 'null'
          description: A provider cursor for a future paginated request, when available.
        has_more:
          type: boolean
        page_size:
          type: integer
          minimum: 0
      additionalProperties: false
    Content:
      type: object
      required:
      - title
      - text
      - media_urls
      - thumbnail_url
      properties:
        title:
          type:
          - string
          - 'null'
        text:
          type:
          - string
          - 'null'
        media_urls:
          type: array
          items:
            type: string
            format: uri
        thumbnail_url:
          type:
          - string
          - 'null'
          format: uri
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
      - success
      - error
      - request_id
      - credits_used
      - credits_remaining
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/Error'
        request_id:
          type: string
        credits_used:
          type: integer
          const: 0
        credits_remaining:
          type:
          - integer
          - 'null'
          minimum: 0
      additionalProperties: false
      example:
        success: false
        error:
          type: INVALID_REQUEST
          message: A required request parameter is missing or invalid
          status: 400
        request_id: req_example123
        credits_used: 0
        credits_remaining: 100
    SocialPost:
      type: object
      required:
      - id
      - platform
      - url
      - content
      - author
      - engagement
      - published_at
      - ext
      properties:
        id:
          type: string
        platform:
          type: string
          enum:
          - linkedin
          - x
          - reddit
          - facebook
          - hackernews
          - tiktok
          - youtube
          - pinterest
          - discourse
        url:
          type:
          - string
          - 'null'
          format: uri
        content:
          $ref: '#/components/schemas/Content'
        author:
          $ref: '#/components/schemas/Author'
        engagement:
          $ref: '#/components/schemas/Engagement'
        published_at:
          type:
          - string
          - 'null'
          format: date-time
        ext:
          type: object
          description: Platform-specific normalized fields.
          additionalProperties: true
      additionalProperties: false
    Author:
      type: object
      required:
      - id
      - username
      - display_name
      - avatar_url
      - verified
      properties:
        id:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        display_name:
          type:
          - string
          - 'null'
        avatar_url:
          type:
          - string
          - 'null'
          format: uri
        verified:
          type:
          - boolean
          - 'null'
      additionalProperties: false
    SocialSearchData:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SocialPost'
      additionalProperties: false
    Engagement:
      type: object
      required:
      - views
      - likes
      - comments
      - shares
      - saves
      properties:
        views:
          type:
          - integer
          - 'null'
        likes:
          type:
          - integer
          - 'null'
        comments:
          type:
          - integer
          - 'null'
        shares:
          type:
          - integer
          - 'null'
        saves:
          type:
          - integer
          - 'null'
      additionalProperties: false
    RawResponse:
      description: The unchanged upstream provider response. Returned only when the request sets raw to true.
    SocialSearchResponse:
      type: object
      required:
      - success
      - platform
      - endpoint
      - data
      - pagination
      - request_id
      - credits_used
      - credits_remaining
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
          enum:
          - linkedin
          - x
          - reddit
          - facebook
          - hackernews
          - tiktok
          - youtube
          - pinterest
          - discourse
        endpoint:
          type: string
        data:
          $ref: '#/components/schemas/SocialSearchData'
        pagination:
          $ref: '#/components/schemas/Pagination'
        raw:
          $ref: '#/components/schemas/RawResponse'
        request_id:
          type: string
          example: req_4QfL8rGv2NwK7zXp
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
          - integer
          - 'null'
          minimum: 0
      additionalProperties: false
    Error:
      type: object
      required:
      - type
      - message
      - status
      properties:
        type:
          type: string
          example: INVALID_REQUEST
        message:
          type: string
          example: A required request parameter is missing or invalid
        status:
          type: integer
          minimum: 400
          maximum: 599
      additionalProperties: false
  responses:
    RateLimited:
      description: The API key exceeded the rate limit.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              type: RATE_LIMITED
              message: The API key has reached 120 requests per minute
              status: 429
            request_id: req_example123
            credits_used: 0
            credits_remaining: 100
    InvalidApiKey:
      description: The API key is missing or invalid.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              type: INVALID_API_KEY
              message: The API key is invalid
              status: 401
            request_id: req_example123
            credits_used: 0
            credits_remaining: 100
    WorkspaceNotActivated:
      description: The workspace is not activated.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              type: WORKSPACE_NOT_ACTIVATED
              message: The workspace email must be activated
              status: 403
            request_id: req_example123
            credits_used: 0
            credits_remaining: 100
    InternalError:
      description: The request could not be completed because of an internal error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              type: INTERNAL_ERROR
              message: Internal server error
              status: 500
            request_id: req_example123
            credits_used: 0
            credits_remaining: 100
    UpstreamProviderError:
      description: The upstream provider request failed or returned an invalid response.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              type: UPSTREAM_PROVIDER_ERROR
              message: The upstream provider request failed
              status: 502
            request_id: req_example123
            credits_used: 0
            credits_remaining: 100
    InsufficientCredits:
      description: The workspace does not have enough credits.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              type: INSUFFICIENT_CREDITS
              message: The workspace does not have enough API credits
              status: 402
            request_id: req_example123
            credits_used: 0
            credits_remaining: 100
    InvalidRequest:
      description: A required request parameter is missing or invalid.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              type: INVALID_REQUEST
              message: A required request parameter is missing or invalid
              status: 400
            request_id: req_example123
            credits_used: 0
            credits_remaining: 100
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your SocialListeningAPI key.
externalDocs:
  description: SocialListeningAPI documentation
  url: https://sociallisteningapi.com/docs/introduction
x-provenance:
  method: harvested
  publisher: SocialListeningAPI
  source: https://api.sociallisteningapi.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)