chatterapi-com Account API

openapi: 3.2.0
info:
  title: ChatterAPI Account 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: Account
  description: Account, usage, health and the generic run alias.
paths:
  /v1/run/{toolId}:
    post:
      operationId: run_tool
      summary: Run any tool by id
      description: 'Generic alias for agents and SDKs: the body is the tool''s arguments object. Costs what the tool costs.'
      tags:
      - Account
      parameters:
      - name: toolId
        in: path
        required: true
        description: Dotted tool id, e.g. reddit.search.
        schema:
          type: string
          enum:
          - reddit.search
          - reddit.nsfw_search
          - reddit.search_comments
          - reddit.search_media
          - reddit.scrape
          - reddit.thread
          - reddit.communities
          - reddit.nsfw_communities
          - reddit.subreddit
          - reddit.subreddit_posts
          - reddit.user
          - reddit.user_status
          - reddit.user_comments
          - reddit.user_posts
          - reddit.user_search
          - reddit.user_analysis
          - reddit.leads
          - x.user
          - x.follow_check
          - x.user_search
          - x.followers
          - x.following
          - x.verified_followers
          - x.tweets
          - x.mentions
          - x.search
          - x.tweet_detail
          - x.replies
          - x.retweeters
          - x.list_members
          - x.leads
          - x.dm_send
          - x.follow
          - x.like
          - x.tweet
          - everywhere.search
          - everywhere.leads
          - everywhere.mentions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      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: {}
                  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/account:
    get:
      operationId: account
      summary: Account and balance
      description: Plan, rate limit, 18+ setting and credit balance for the key's account. Free.
      tags:
      - Account
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - credits
                - requestId
                - cached
                properties:
                  data:
                    type: object
                  credits:
                    $ref: '#/components/schemas/Credits'
                  requestId:
                    type: string
                    examples:
                    - req_01JA7Q3V8K2N4P5R6S7T8V
                  cached:
                    type: boolean
                  warnings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Warning'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
  /v1/usage:
    get:
      operationId: usage
      summary: Usage by tool and day
      description: Credits spent per tool and per day for the key's account. Free.
      tags:
      - Account
      parameters:
      - name: days
        in: query
        required: false
        description: Days to include.
        schema:
          type: integer
          default: 7
          minimum: 1
          maximum: 90
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
  /v1/health:
    get:
      operationId: health
      summary: Health check
      description: Returns ok, the version and the server time. No key needed.
      tags:
      - Account
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  version:
                    type: string
                  time:
                    type: string
        '500':
          $ref: '#/components/responses/Error500'
components:
  headers:
    x-request-id:
      description: request id
      schema:
        type: string
    x-credits-remaining:
      description: credits remaining
      schema:
        type: integer
    x-ratelimit-limit:
      description: ratelimit limit
      schema:
        type: integer
    x-ratelimit-reset:
      description: ratelimit reset
      schema:
        type: integer
    x-ratelimit-remaining:
      description: ratelimit remaining
      schema:
        type: integer
    x-credits-charged:
      description: credits charged
      schema:
        type: integer
  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
    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
    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
    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
    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
  schemas:
    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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: ca_live_ or ca_test_ key