chatterapi-com Everywhere API

openapi: 3.2.0
info:
  title: ChatterAPI Everywhere API
  version: 0.1.0
  description: 'ChatterAPI is a Reddit and X data API for developers and AI agents. One API key and one credit balance. REST at https://api.chatterapi.com/v1 and a hosted MCP server at https://api.chatterapi.com/mcp. Every response includes the credits it cost. Failed calls cost 0. Credit costs: Reddit read: any search, one post, subreddit profile or feed, user profile, account status, post or comment history: 2; Reddit thread with comments, or an X lead finder page: 3; Reddit lead finder page: 4; X read: profile, tweets, search, replies, one page of followers: 3; X verified followers, per 20: 4; Search everywhere (Reddit + X): 5; Lead finder everywhere: 6; Brand mentions everywhere: 7; X action from your connected account (follow, like, retweet, tweet): 5; X DM send: 10; Failed call or bad input: 0.'
  contact:
    name: ChatterAPI
    email: piyushh@amplifyxlabs.com
    url: https://chatterapi.com
  license:
    name: Proprietary
    url: https://chatterapi.com/terms
  x-independence: ChatterAPI is independent and not affiliated with Reddit, Inc. or X Corp.
servers:
- url: https://chatterapi.com
  description: Production. Paths start with /v1.
security:
- bearer: []
tags:
- name: everywhere
  description: Tools that search Reddit and X together.
paths:
  /v1/search:
    get:
      operationId: everywhere_search
      summary: Search Everywhere
      description: 'Search one keyword across Reddit and X at once and get one merged list of posts and tweets, each with platform, author, community, score, link and date. Costs 5 credits for a page from both platforms (less if one platform has no more pages). Tip: sort=new for monitoring; sort=top ranks each platform''s most-engaged items fairly against each other. Costs up to 5 credits.'
      tags:
      - everywhere
      x-credits: 5
      x-mcp-tool: everywhere_search
      parameters:
      - name: q
        in: query
        required: true
        description: Search text. Quotes and OR work on both platforms.
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: new for monitoring; top ranks each platform's most engaged items fairly.
        schema:
          default: relevance
          type: string
          enum:
          - relevance
          - new
          - top
      - name: time
        in: query
        required: false
        description: Time window.
        schema:
          default: month
          type: string
          enum:
          - hour
          - day
          - week
          - month
          - year
          - all
      - name: limit
        in: query
        required: false
        description: Max rows per platform (1-50); a merged page holds up to twice this.
        schema:
          default: 20
          type: integer
          minimum: 1
          maximum: 50
      - name: nsfw
        in: query
        required: false
        description: Include adult Reddit posts. true needs the 18+ setting; the price is the same.
        schema:
          type:
          - boolean
          - string
      - name: cursor
        in: query
        required: false
        description: Opaque cursor from the previous response's page.nextCursor.
        schema:
          type: string
          minLength: 1
          maxLength: 2048
      responses:
        '200':
          description: Success
          headers:
            x-request-id:
              $ref: '#/components/headers/x-request-id'
            x-credits-charged:
              $ref: '#/components/headers/x-credits-charged'
            x-credits-remaining:
              $ref: '#/components/headers/x-credits-remaining'
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - credits
                - requestId
                - cached
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Mention'
                  page:
                    $ref: '#/components/schemas/PageInfo'
                  credits:
                    $ref: '#/components/schemas/Credits'
                  requestId:
                    type: string
                    examples:
                    - req_01JA7Q3V8K2N4P5R6S7T8V
                  cached:
                    type: boolean
                  warnings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Warning'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '504':
          $ref: '#/components/responses/Error504'
  /v1/leads:
    get:
      operationId: everywhere_leads
      summary: Lead Finder
      description: 'Find people on Reddit and X who are asking for a recommendation, comparing tools or complaining about one in your category, ranked by an intent score from 0 to 1 with the phrases that matched. Costs 6 credits per page (4 if only one platform answers). Tip: start with your category in two or three words and add up to five competitors. Costs up to 6 credits.'
      tags:
      - everywhere
      x-credits: 6
      x-mcp-tool: everywhere_leads
      parameters:
      - name: q
        in: query
        required: true
        description: Your product category or the problem it solves, e.g. crm or cold email. 1-60 characters.
        schema:
          type: string
      - name: competitors
        in: query
        required: false
        description: Up to 5 tools people might switch away from, e.g. hubspot,pipedrive.
        schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        style: form
        explode: false
      - name: exclude
        in: query
        required: false
        description: Up to 10 words that disqualify an item.
        schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        style: form
        explode: false
      - name: time
        in: query
        required: false
        description: How far back to look.
        schema:
          default: month
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: minScore
        in: query
        required: false
        description: Minimum intent score from 0 to 1.
        schema:
          default: 0.3
          type: number
          minimum: 0
          maximum: 1
      - name: intents
        in: query
        required: false
        description: 'Which intents to return. Default: all three.'
        schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        style: form
        explode: false
      - name: cursor
        in: query
        required: false
        description: Opaque cursor from the previous response's page.nextCursor.
        schema:
          type: string
          minLength: 1
          maxLength: 2048
      - name: subreddit
        in: query
        required: false
        description: Limit the Reddit side to one subreddit.
        schema:
          type: string
      - name: lang
        in: query
        required: false
        description: Tweet language, 2 letters.
        schema:
          default: en
          type: string
          pattern: ^[a-z]{2}$
      responses:
        '200':
          description: Success
          headers:
            x-request-id:
              $ref: '#/components/headers/x-request-id'
            x-credits-charged:
              $ref: '#/components/headers/x-credits-charged'
            x-credits-remaining:
              $ref: '#/components/headers/x-credits-remaining'
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - credits
                - requestId
                - cached
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
                  page:
                    $ref: '#/components/schemas/PageInfo'
                  credits:
                    $ref: '#/components/schemas/Credits'
                  requestId:
                    type: string
                    examples:
                    - req_01JA7Q3V8K2N4P5R6S7T8V
                  cached:
                    type: boolean
                  warnings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Warning'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '504':
          $ref: '#/components/responses/Error504'
  /v1/mentions:
    get:
      operationId: everywhere_mentions
      summary: Brand Mentions
      description: 'Find every recent mention of a brand or product name across Reddit posts, Reddit comments and X, merged newest first. Supports other spellings, exclusion words and your own accounts to skip. Costs 7 credits for a page from all three sources. Tip: add your own handles to excludeAuthors so you only see what others say. Costs up to 7 credits.'
      tags:
      - everywhere
      x-credits: 7
      x-mcp-tool: everywhere_mentions
      parameters:
      - name: q
        in: query
        required: true
        description: Brand or product name. 1-100 characters.
        schema:
          type: string
      - name: aliases
        in: query
        required: false
        description: Up to 5 other spellings, e.g. chatterapi.io.
        schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        style: form
        explode: false
      - name: exclude
        in: query
        required: false
        description: Up to 10 words that disqualify a mention.
        schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        style: form
        explode: false
      - name: excludeAuthors
        in: query
        required: false
        description: Up to 20 of your own accounts to skip (Reddit usernames or X handles).
        schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        style: form
        explode: false
      - name: time
        in: query
        required: false
        description: How far back to look.
        schema:
          default: week
          type: string
          enum:
          - day
          - week
          - month
      - name: strict
        in: query
        required: false
        description: Keep only items whose text contains a term.
        schema:
          type:
          - boolean
          - string
      - name: cursor
        in: query
        required: false
        description: Opaque cursor from the previous response's page.nextCursor.
        schema:
          type: string
          minLength: 1
          maxLength: 2048
      responses:
        '200':
          description: Success
          headers:
            x-request-id:
              $ref: '#/components/headers/x-request-id'
            x-credits-charged:
              $ref: '#/components/headers/x-credits-charged'
            x-credits-remaining:
              $ref: '#/components/headers/x-credits-remaining'
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - credits
                - requestId
                - cached
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Mention'
                  page:
                    $ref: '#/components/schemas/PageInfo'
                  credits:
                    $ref: '#/components/schemas/Credits'
                  requestId:
                    type: string
                    examples:
                    - req_01JA7Q3V8K2N4P5R6S7T8V
                  cached:
                    type: boolean
                  warnings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Warning'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '504':
          $ref: '#/components/responses/Error504'
components:
  responses:
    Error504:
      description: 'Gateway timeout: upstream_timeout'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - upstream_timeout
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: upstream_timeout
              message: See docsUrl.
              retryable: true
              docsUrl: https://chatterapi.com/docs/errors#upstream_timeout
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error401:
      description: 'Unauthorized: missing_key, invalid_key, key_revoked'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - missing_key
                    - invalid_key
                    - key_revoked
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: missing_key
              message: See docsUrl.
              retryable: false
              docsUrl: https://chatterapi.com/docs/errors#missing_key
              instructionsForAgent: Ask the user for their ChatterAPI key (it starts with ca_live_). Do not retry without one.
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error429:
      description: 'Too many requests: rate_limited'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: rate_limited
              message: See docsUrl.
              retryable: true
              docsUrl: https://chatterapi.com/docs/errors#rate_limited
              instructionsForAgent: Too many requests per second. Wait retryAfter seconds, then retry once.
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error400:
      description: 'Bad request: invalid_input'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - invalid_input
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: invalid_input
              message: See docsUrl.
              retryable: false
              docsUrl: https://chatterapi.com/docs/errors#invalid_input
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error402:
      description: 'Payment required: insufficient_credits'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - insufficient_credits
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: insufficient_credits
              message: See docsUrl.
              retryable: false
              docsUrl: https://chatterapi.com/docs/errors#insufficient_credits
              topupUrl: https://chatterapi.com/dashboard/billing
              instructionsForAgent: The user's ChatterAPI balance is too low for this call. Tell them and share the topupUrl. Do not retry.
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error404:
      description: 'Not found: not_found'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - not_found
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: not_found
              message: See docsUrl.
              retryable: false
              docsUrl: https://chatterapi.com/docs/errors#not_found
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error502:
      description: 'Bad gateway: upstream_error'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - upstream_error
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: upstream_error
              message: See docsUrl.
              retryable: true
              docsUrl: https://chatterapi.com/docs/errors#upstream_error
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error500:
      description: 'Internal error: internal'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - internal
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: internal
              message: See docsUrl.
              retryable: true
              docsUrl: https://chatterapi.com/docs/errors#internal
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
    Error403:
      description: 'Forbidden: account_suspended, scope_denied'
      headers:
        x-request-id:
          $ref: '#/components/headers/x-request-id'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - requestId
            properties:
              error:
                type: object
                required:
                - code
                - message
                - retryable
                - docsUrl
                properties:
                  code:
                    type: string
                    enum:
                    - account_suspended
                    - scope_denied
                  message:
                    type: string
                  retryable:
                    type: boolean
                  docsUrl:
                    type: string
                    format: uri
                  topupUrl:
                    type: string
                    format: uri
                  retryAfter:
                    type: integer
                  instructionsForAgent:
                    type: string
              requestId:
                type: string
          example:
            error:
              code: account_suspended
              message: See docsUrl.
              retryable: false
              docsUrl: https://chatterapi.com/docs/errors#account_suspended
              instructionsForAgent: This ChatterAPI account is suspended. Tell the user to contact support. Do not retry.
            requestId: req_01JA7Q3V8K2N4P5R6S7T8V
  headers:
    x-ratelimit-limit:
      description: ratelimit limit
      schema:
        type: integer
    x-ratelimit-reset:
      description: ratelimit reset
      schema:
        type: integer
    x-request-id:
      description: request id
      schema:
        type: string
    x-credits-remaining:
      description: credits remaining
      schema:
        type: integer
    x-ratelimit-remaining:
      description: ratelimit remaining
      schema:
        type: integer
    x-credits-charged:
      description: credits charged
      schema:
        type: integer
  schemas:
    Mention:
      type: object
      properties:
        platform:
          type: string
          enum:
          - reddit
          - x
        kind:
          type: string
          enum:
          - post
          - comment
          - tweet
        id:
          type: string
        url:
          type: string
        text:
          type: string
        author:
          type:
          - string
          - 'null'
        authorUrl:
          type:
          - string
          - 'null'
        community:
          type:
          - string
          - 'null'
        score:
          type:
          - number
          - 'null'
        createdAt:
          anyOf:
          - type: string
            description: ISO 8601 UTC timestamp
          - type: 'null'
      required:
      - platform
      - kind
      - id
      - url
      - text
      - author
      - authorUrl
      - community
      - score
      - createdAt
      additionalProperties: false
    Warning:
      type: object
      properties:
        code:
          type: string
          enum:
          - partial_data
          - stale_data
          - platform_unavailable
          - source_unavailable
        platform:
          type: string
          enum:
          - reddit
          - x
        source:
          type: string
        fields:
          type: array
          items:
            type: string
      required:
      - code
      additionalProperties: false
    Credits:
      type: object
      required:
      - charged
      - remaining
      properties:
        charged:
          type: integer
        remaining:
          type: integer
    Lead:
      type: object
      properties:
        platform:
          type: string
          enum:
          - reddit
          - x
        kind:
          type: string
          enum:
          - post
          - comment
          - tweet
        id:
          type: string
        url:
          type: string
        text:
          type: string
        author:
          type:
          - string
          - 'null'
        authorUrl:
          type:
          - string
          - 'null'
        community:
          type:
          - string
          - 'null'
        score:
          type:
          - number
          - 'null'
        createdAt:
          anyOf:
          - type: string
            description: ISO 8601 UTC timestamp
          - type: 'null'
        intent:
          type: string
          enum:
          - asking_for_recommendation
          - comparing_tools
          - complaining_about_tool
          - other
        intentScore:
          type: number
          minimum: 0
          maximum: 1
        matchedTerms:
          type: array
          items:
            type: string
      required:
      - platform
      - kind
      - id
      - url
      - text
      - author
      - authorUrl
      - community
      - score
      - createdAt
      - intent
      - intentScore
      - matchedTerms
      additionalProperties: false
    PageInfo:
      type: object
      properties:
        nextCursor:
          type:
          - string
          - 'null'
        hasMore:
          type: boolean
      required:
      - nextCursor
      - hasMore
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: ca_live_ or ca_test_ key