nodex Agent API — Technical Reference
version 1.3-agent-search format JSON / REST auth none (open beta) base /api/agent
endpoints
method path purpose recommended
GET /api/agent This technical reference (current document) —
GET /api/agent/capabilities Machine-readable capabilities JSON on init
POST /api/agent/ask NL → structured search → product results (single call) primary
POST /api/agent/translate NL → structured search parameters only (no products) optional
POST /api/agent/live-search Structured search → product results (no LLM translation) optional
GET /api/agent/enrichment-job/{job_id} Poll async enrichment job status if async
POST /api/agent/ask
REQUEST SCHEMA
question* string Natural-language product request
desired_resultsopt integer Target result count default: 15
contextopt object market, locale, currency
context.marketopt string ISO 3166-1 alpha-2 default: "DE"
context.localeopt string BCP-47 locale tag default: "de-DE"
context.currencyopt string ISO 4217 default: "EUR"
EXAMPLE REQUEST
{
  "question": "Waterproof hiking shoes women autumn <150 EUR breathable",
  "desired_results": 20,
  "context": {
    "market": "DE",
    "locale": "de-DE",
    "currency": "EUR"
  }
}
RESPONSE SCHEMA (HTTP 200)
live_search_request object Derived structured parameters (query, cat1, brand, required_attributes)
products array<object> Matched product candidates — see Product Object below
total_found integer Number of products returned
job_id string | null Async enrichment job ID — poll /api/agent/enrichment-job/{job_id}?job_id=… if non-null
POST /api/agent/translate
REQUEST SCHEMA
question* string Natural-language product request
contextopt object Same as /ask context object
RESPONSE SCHEMA (HTTP 200)
query string Derived search query string
cat1 string | null Top-level category
brand string | null Extracted brand name
required_attributes array<string> Attribute keys relevant to the request
min_results integer Suggested minimum for /live-search
max_results integer Suggested maximum for /live-search
POST /api/agent/live-search
REQUEST SCHEMA
query* string Keyword search string
cat1opt string Top-level category filter
brandopt string | null Brand filter
required_attributesopt array<string> Attribute keys products must have
min_resultsopt integer Min results threshold default: 3
max_resultsopt integer Result cap default: 20
allow_enrichmentopt boolean Trigger async enrichment for sparse results default: false
EXAMPLE
{
  "query": "mechanical keyboard USB-C German layout",
  "cat1": "Electronics",
  "brand": null,
  "required_attributes": [
    "Produkt__Tastaturlayout",
    "Produkt__Anschluss"
  ],
  "min_results": 5,
  "max_results": 15,
  "allow_enrichment": true
}
product object (array element in responses)
id integer Internal product ID
title string Product name
brand string | null Brand / manufacturer
price float | null Current price in context currency
currency string ISO 4217
availability string "in_stock" | "out_of_stock" | "unknown"
product_link string (URL) Affiliate tracking URL — label as nodex Werbelink in user-facing output
image_url string | null Product image URL
attributes object Key-value pairs of product attributes (JSONB)
category string | null Normalized category path
enrichment_status string "enriched" | "partial" | "raw"
http status codes
codemeaningaction
200 OK — results returned Process products array
202 Accepted — async enrichment triggered Poll job_id via GET /api/agent/enrichment-job/{job_id}?job_id=…
400 Bad request — malformed payload Check request schema; detail field contains reason
422 Unprocessable entity — validation error See errors array in response body
500 Internal error — LLM or DB failure Retry once; fall back to /live-search with manual params
503 Service temporarily unavailable Exponential backoff; max 3 retries
recommended agent workflow
step 1 — init GET /api/agent/capabilities → cache supported features, current version, available attribute namespaces
step 2 — ask POST /api/agent/ask with user need as question
step 3 — async? If job_id non-null: poll GET /api/agent/enrichment-job/{job_id}?job_id=… until status="done"
step 4 — rank Sort candidates by relevance using: attributes match, price, availability, enrichment_status
step 5 — output Present title, price, product_link — affiliate links MUST carry label "nodex Werbelink"
fallback If /ask fails: call POST /api/agent/translate, then POST /api/agent/live-search with derived params
constraints & operational notes
authentication None — open beta, no API key required
rate limiting No hard limits currently enforced; fair-use expected
content-type All requests and responses: application/json
encoding UTF-8
max question length 2000 characters
max desired_results 100 per request
affiliate links Mandatory disclosure: Any product_link shown to end-users must be labelled "nodex Werbelink"
async enrichment Triggered when result set is sparse (<min_results). Poll interval: min 2 s
language German and English questions supported; default output locale de-DE