Analyze Message

curl -X POST 'https://api.getchatads.com/v1/chatads/messages' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "message": "The Bose QuietComfort Ultra earbuds are great for commuting. They have solid noise cancellation and a comfortable fit. Battery life is around six hours, which is enough for most people."
  }'

{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "Bose QuietComfort Ultra earbuds",
        "url": "https://www.amazon.com/dp/B0CD2FSRDD/?tag=yourtag-20",
        "products": [
          {
            "title": "Bose QuietComfort Ultra Bluetooth Earbuds...",
            "stars": 3.8,
            "reviews": 9765,
            "price": 199.0,
            "image": "https://m.media-amazon.com/images/I/51example.jpg"
          }
        ]
      }
    ],
    "requested": 1,
    "returned": 1,
    "billed": true
  },
  "error": null,
  "meta": {
    "request_id": "0f04eb2e-820a-460a-8427-ccc1a6233b6a",
    "timestamp": "2026-03-11T13:57:42.074Z",
    "version": "1.0.0",
    "usage": {
      "monthly_requests": 13,
      "daily_requests": 3,
      "daily_limit": 10000,
      "is_free_tier": false
    }
  }
}

POST

chatads

messages

curl -X POST 'https://api.getchatads.com/v1/chatads/messages' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "message": "The Bose QuietComfort Ultra earbuds are great for commuting. They have solid noise cancellation and a comfortable fit. Battery life is around six hours, which is enough for most people."
  }'

{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "Bose QuietComfort Ultra earbuds",
        "url": "https://www.amazon.com/dp/B0CD2FSRDD/?tag=yourtag-20",
        "products": [
          {
            "title": "Bose QuietComfort Ultra Bluetooth Earbuds...",
            "stars": 3.8,
            "reviews": 9765,
            "price": 199.0,
            "image": "https://m.media-amazon.com/images/I/51example.jpg"
          }
        ]
      }
    ],
    "requested": 1,
    "returned": 1,
    "billed": true
  },
  "error": null,
  "meta": {
    "request_id": "0f04eb2e-820a-460a-8427-ccc1a6233b6a",
    "timestamp": "2026-03-11T13:57:42.074Z",
    "version": "1.0.0",
    "usage": {
      "monthly_requests": 13,
      "daily_requests": 3,
      "daily_limit": 10000,
      "is_free_tier": false
    }
  }
}

Analyzes a user message to extract product keywords and return relevant affiliate links.

Using the API Explorer: Click “Try It” on the right to test this endpoint interactively. Enter your API key from app.getchatads.com/api/keys in the Authorization header field.

Request Body

message

string

required

The user message to analyze. Required, max 10,000 characters. Min 10 words.

string

IP address (IPv4 or IPv6) for country detection. Anything identified as non-US will be skipped.

country

string

Country code (e.g., ‘US’). If provided, skips IP-based country detection.

extraction_mode

string

default:"standard"

Controls how product keywords are extracted from the message:

none — skips product extraction and all filters (country, language, keyword, IP); finds an offer on the provided string
standard — default full extraction

resolution_mode

string

default:"standard"

Controls how extracted keywords are resolved to affiliate URLs:

none — doesn’t look for offers; returns extracted product only
standard — default full resolution

max_offers

integer

default:"1"

Max distinct keyterms with offers extracted (1-3). Defaults to 1.

max_products_per_offer

integer

default:"1"

Max product offers per keyterm (1-3). Defaults to 1.

metadata

JSON object

Arbitrary JSON key-value pairs to attach to the request. Passed through and returned in the response for your own tracking purposes. Example: {"session_id": "abc123", "user_id": "u_456"}.

Response

data

object

Show properties

status

string

required

Request outcome: “filled” (offer found), “no_offer” (no affiliate offer available, billable), “no_brand_found” (brand-only mode enabled but no brand detected, billable), “message_too_short” (fewer than 10 words, non-billable), “message_too_long” (over 10,000 chars, non-billable), “country_not_allowed” (country param not in allowed list, non-billable), “blocked_keyword” (message contains blocked content, non-billable), “language_not_allowed” (detected language not allowed, non-billable), or “ip_country_not_allowed” (IP geo-location country not allowed, non-billable).

offers

array

required

Array of affiliate offers. Only contains offers with URLs (all offers are usable). Never null.

Show Offer object properties

link_text

string

Text to use for the affiliate link

url

string

Affiliate link URL (empty when resolution_mode=none)

match_start

integer

Zero-based character offset into the original message pointing at the preferred occurrence of link_text (non-preamble when multiple occurrences exist). Omitted when the sidecar didn’t provide an offset (e.g. extraction_mode=none with a caller-supplied keyword), or when sanitize-step transformations (ignored-keyword removal, CRLF normalization, whitespace collapse) prevent reliable re-mapping into the original message coordinates within a 200-character forward-scan window. When omitted, fall back to a first-match string replace of link_text in message.

match_end

integer

Exclusive character offset paired with match_start. Use message[match_start:match_end] to wrap the exact span the API recommends. Omitted under the same conditions as match_start.

is_branded

boolean

Whether the winning extracted term was classified as brand-derived (true) or generic (false). Omitted when no classification is available (e.g. extraction_mode=none, where the caller supplies their own term).

products

array

Resolved products for this term (carousel). products[0] is the ranking-best pick. Up to max_products_per_offer entries, deduped by catalog product ID across offers.

Show Product object properties

title

string

Product title from search result

description

string

Product description/snippet from search result

stars

number

Raw product rating on the catalog’s scale (e.g., 4.5 on a 5-star catalog).

reviews

integer

Number of product reviews

image

string

Product image URL

price

number

Product price in USD (canonical). Only present when available from search results.

currency

string

ISO 4217 currency code for price. Always “USD” today.

price_local

number

Raw catalog price in the source catalog’s currency. Only populated for non-USD catalogs.

currency_local

string

ISO 4217 currency code for price_local. Only populated for non-USD catalogs.

requested

integer

required

Number of offers requested.

returned

integer

required

Number of offers returned (equals length of offers array).

billed

boolean

required

Whether this request counted toward your usage billing.

error

object

Error details when request fails. Null for successful requests. Check error == null to determine success.

meta

object

Show properties

request_id

string

required

Unique request ID for debugging.

timestamp

string

ISO 8601 timestamp of the request

version

string

API version (e.g., “1.0.0”)

country

string

Detected/provided country

timing_ms

object

Show timing_ms fields

total_ms

number

End-to-end request time

processor_ms

number

Offer pipeline only (extract → score → resolve). Excludes startup gates like brand check and monetizable classifier.

startup

object

Show startup fields

edge_ms

number

Edge/network time

auth_ms

number

API key auth overhead, excluding team_lookup_ms and ratelimit_ms sub-spans

team_lookup_ms

number

Team settings lookup time (includes cache hits)

ratelimit_ms

number

Rate limit check time (omitted when skipped)

validation_ms

number

Sanitize + brand-gate + monetizable classifier wall-clock (parent of classification_ms)

filter_ms

number

Country/language/keyword filter time (omitted when skipped)

lang_detect_ms

number

whatlang+lingua language detection time (omitted when not run)

classification_ms

number

m2v monetizable classifier sub-span (omitted when not run)

extraction

object

Show extraction fields

total_ms

number

Total extraction phase time

nlp_ms

number

NLP sidecar RTT

nlp_validate_ms

number

Go-side validateProducts post-RTT (always emitted)

nlp_extract_ms

number

Sidecar extraction time (omitted when not reported)

nlp_scoring_ms

number

Sidecar scoring time (omitted when not reported)

nlp_search_ms

number

Sidecar search time (omitted when not reported)

lookup

object

Show lookup fields

total_ms

number

Total resolution/lookup phase time

vector_fallback_ms

number

Bare-term fallback vector call time (omitted when not run)

resolve_ms

number

URL resolution time

usage

object

Usage statistics

curl -X POST 'https://api.getchatads.com/v1/chatads/messages' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "message": "The Bose QuietComfort Ultra earbuds are great for commuting. They have solid noise cancellation and a comfortable fit. Battery life is around six hours, which is enough for most people."
  }'

{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "Bose QuietComfort Ultra earbuds",
        "url": "https://www.amazon.com/dp/B0CD2FSRDD/?tag=yourtag-20",
        "products": [
          {
            "title": "Bose QuietComfort Ultra Bluetooth Earbuds...",
            "stars": 3.8,
            "reviews": 9765,
            "price": 199.0,
            "image": "https://m.media-amazon.com/images/I/51example.jpg"
          }
        ]
      }
    ],
    "requested": 1,
    "returned": 1,
    "billed": true
  },
  "error": null,
  "meta": {
    "request_id": "0f04eb2e-820a-460a-8427-ccc1a6233b6a",
    "timestamp": "2026-03-11T13:57:42.074Z",
    "version": "1.0.0",
    "usage": {
      "monthly_requests": 13,
      "daily_requests": 3,
      "daily_limit": 10000,
      "is_free_tier": false
    }
  }
}

API Introduction

​Request Body

​Response

Request Body

Response