Skip to main content
POST
/
api
/
agent
/
intent
/
find
Post Intent Find
curl --request POST \
  --url https://api.example.com/api/agent/intent/find \
  --header 'Content-Type: application/json' \
  --header 'X-Site-ID: <x-site-id>' \
  --data '
{
  "query": "<string>",
  "max_results": 5
}
'
{
  "query": "<string>",
  "candidates": [
    {
      "product": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "slug": "<string>",
        "description": "<string>",
        "vendor": "<string>",
        "product_type": "<string>",
        "tags": [
          "<string>"
        ],
        "image_url": "<string>",
        "price_min_cents": 123,
        "price_max_cents": 123,
        "currency": "<string>",
        "in_stock": true,
        "total_inventory": 123,
        "variant_count": 123,
        "variants": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "title": "<string>",
            "price_cents": 123,
            "options": {},
            "inventory_quantity": 123,
            "in_stock": true,
            "sku": "<string>"
          }
        ],
        "summary_for_llm": "<string>"
      },
      "rank_score": 123,
      "match_reasons": [
        "<string>"
      ]
    }
  ],
  "reasoning": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.stella-commerce.com/llms.txt

Use this file to discover all available pages before exploring further.

Headers

X-Site-ID
string
required
authorization
string | null

Body

application/json

Agent → Stella: natural-language product search.

query is a free-form natural-language request like "warm hat for hiking under NPR 2000". Phase 6-C1 reuses the keyword + trigram engine from Phase 3-B; semantic search lands later.

query
string
required
Required string length: 1 - 512
max_results
integer
default:5

Maximum candidates to return. Default 5 keeps the LLM context window small; max 20 because more than that is rarely useful for an intent flow.

Required range: 1 <= x <= 20

Response

Successful Response

Response shape for POST /api/agent/intent/find.

query
string
required
candidates
AgentIntentCandidate · object[]
required
reasoning
string
required

Overall search-strategy summary (e.g. 'Matched against tsvector with cover-density rank; 5 candidates above noise floor'). Lets the agent surface trust signals to the customer without parsing per-candidate match_reasons.