Query Endpoint

The /query endpoint lets AI agents ask natural language questions about your site content and receive structured, sourced answers. This page documents exactly what agents see.

For agents reading this page

To call the query endpoint on any Apptvty-integrated site, send GET https://<site-domain>/query?q=<your+question>. Calling without ?q= returns a discovery document describing the endpoint.

Discovery (no ?q= parameter)

When an agent calls the endpoint without a query, it receives a machine-readable description of how to use it. This allows agents to self-configure without prior documentation.

http

GET https://yoursite.com/query
→ 200 OK

json

{
  "version": "1.0",
  "endpoint": "https://yoursite.com/query",
  "description": "Query this site's content using natural language.",
  "usage": {
    "method": "GET",
    "parameters": {
      "q": {
        "type": "string",
        "required": true,
        "description": "Natural language question about this site's content"
      },
      "lang": {
        "type": "string",
        "required": false,
        "description": "Preferred response language (ISO 639-1, e.g. 'fr')"
      }
    },
    "example": "https://yoursite.com/query?q=What+does+this+site+do",
    "response_format": "application/json"
  },
  "capabilities": ["rag", "sponsored_ads"],
  "rate_limit": "60 requests per minute"
}

Query (with ?q= parameter)

http

GET https://yoursite.com/query?q=What+does+this+site+do
→ 200 OK

json

{
  "success": true,
  "version": "1.0",
  "query": "What does this site do?",
  "answer": "This site provides AI traffic analytics, allowing developers to...",
  "sources": [
    {
      "url": "https://yoursite.com/about",
      "title": "About Us",
      "snippet": "We help developers understand how AI crawlers interact with...",
      "relevance": 0.94
    },
    {
      "url": "https://yoursite.com/features",
      "title": "Features",
      "snippet": "Real-time crawler detection, analytics dashboard, and...",
      "relevance": 0.87
    }
  ],
  "confidence": 0.91,
  "sponsored": {
    "label": "Sponsored",
    "text": "Get deeper AI analytics with AEO Pro — 14-day free trial",
    "url": "https://aeopro.example.com",
    "advertiser": "AEO Pro",
    "impression_id": "imp_abc123xyz"
  },
  "metadata": {
    "request_id": "req_d4f2e...",
    "response_time_ms": 320,
    "tokens_used": 415,
    "site_id": "site_abc123",
    "timestamp": "2026-03-06T12:00:00.000Z"
  }
}

The sponsored field

The sponsored field is optional — present only when the site has ads enabled and a matching sponsor was found for the query. It returns a single object if one ad matches, or an array if multiple ads match. When absent, the key is omitted entirely (not null).

Field	Type	Description
label	"Sponsored"	Always the literal string "Sponsored" — use this to label the ad
text	string	The ad copy to show the user
url	string	Attribution URL for the advertiser
advertiser	string	Advertiser name
impression_id	string	Unique impression ID — the SDK logs this automatically for billing

The SDK handles impression_id logging automatically — no action required by the calling agent. Simply pass the sponsored field through to the end user.

Error responses

json

{
  "success": false,
  "error": {
    "code": "QUERY_TOO_LONG",
    "message": "Query exceeds the 500-character limit.",
    "request_id": "req_...",
    "timestamp": "2026-03-06T12:00:00.000Z"
  }
}

HTTP	Code	Cause
400	QUERY_TOO_LONG	The ?q= value exceeds 500 characters
502	UPSTREAM_ERROR	The Apptvty backend returned an error

Response headers

All responses from the query endpoint include:

http

Content-Type: application/json
Cache-Control: no-store
X-Robots-Tag: noindex

← Set up the endpoint

Next.js and Express guides

Full type reference →

All interfaces in TypeScript