# NexorAIQ Developer & API Full Reference (Full Context)

> Complete technical specifications, REST endpoints, GraphQL schemas, integration recipes, and architecture details for AI agents and LLMs browsing NexorAIQ Cloud.

## 1. Platform Overview
NexorAIQ is a cloud-native Search AI platform providing full-text, vector, semantic, and hybrid search solutions for e-commerce and enterprise applications.

### Core Stack
- **Typesense**: Primary lexical indexing engine offering sub-5ms typo-tolerant full-text search.
- **Qdrant**: High-dimensional vector database for semantic similarity, neural embeddings, and HNSW indexes.
- **PostgreSQL**: Transactional database for account multi-tenancy, API keys, index catalogs, and synonym dictionaries.
- **ClickHouse**: Real-time analytical engine aggregating search query streams, zero-result tracking, and CTR logs.
- **Redis & BullMQ**: Background job queues managing asynchronous catalog synchronization.
- **MinIO**: S3-compatible asset store for product imagery and vector checkpoints.

---

## 2. Authentication
All API requests require authentication using an API key passed in the request header:
- Header name: `x-api-key`
- Format: `sk-live-...` or `sk-test-...`

Example:
```bash
curl -X POST https://api.nexoraiq.tech/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"query": "wireless headphones", "limit": 10}'
```

---

## 3. REST API Specifications

### 3.1 Search (`GET /search` or `POST /search`)
Executes typo-tolerant full-text, vector semantic, or hybrid search. GET takes query params; POST takes the same fields as a JSON body.

**Parameters:** `q`, `searchType` (keyword | vector | hybrid, default hybrid), `storeView`, `page` (default 1), `limit` (1-100, default 20), `sortBy` (relevance, price:asc, price:desc, title:asc, title:desc, rating:desc, created_at:desc), `category`, `minPrice`, `maxPrice`, `tags` (comma-separated for GET, array for POST), `inStockOnly` (default false), `fields` (comma-separated hit fields, default all), `hasFilter` (return facets, default true), `sessionId`, `userId`, `device`.

**Tracking headers (optional):** `x-session-id`, `x-user-id`, `x-device` (same as `sessionId`, `userId`, `device`).

**Request Payload (POST):**
```json
{
  "q": "running shoes",
  "storeView": "en",
  "page": 1,
  "limit": 20,
  "searchType": "hybrid",
  "category": "Footwear",
  "minPrice": 50,
  "maxPrice": 200,
  "inStockOnly": true,
  "sortBy": "price:asc",
  "fields": "id,title,sku,price,imageUrl",
  "sessionId": "sess_abc123",
  "userId": "usr_456",
  "device": "desktop"
}
```

**Response Payload:**
```json
{
  "total_found": 142,
  "search_time_ms": 4,
  "responseId": "resp_9a8b7c6d5e",
  "redirected": false,
  "hits": [
    {
      "id": "prod_101",
      "sku": "SHOE-RUN-BLK-10",
      "name": "Pro Air Zoom Running Shoes",
      "price": 129.99,
      "inventory": 45,
      "category": "Footwear",
      "imageUrl": "https://cdn.example.com/shoes.jpg"
    }
  ]
}
```

### 3.2 Autocomplete (`GET /search/autocomplete` or `POST /search/autocomplete`)
Real-time type-ahead suggestions for shopper queries.

**Parameters:** `q` (required), `type` (query | brand | category | product | all, default query), `storeView`, `limit` (1-20, default 10), `sessionId`, `userId`, `device`. Tracking headers `x-session-id`, `x-user-id`, `x-device` also accepted.

**Request Payload (POST):**
```json
{
  "q": "iph",
  "storeView": "en",
  "type": "query",
  "limit": 10,
  "sessionId": "sess_abc123"
}
```

### 3.3 Search Overlay (`GET /search/overlay` or `POST /search/overlay`)
Returns suggestions, category and brand quick-links, and product previews in one call.

**Parameters:** `q`, `storeView`, `limit` (1-12, default 5), `suggestion`, `category`, `brand` (booleans, default true), `suggestionLimit`, `categoryLimit`, `brandLimit` (default 5), `inStockOnly`, `categoryFilter`, `minPrice`, `maxPrice`, `tags`, `sortBy`, `searchType`, `sessionId`, `userId`, `device`. Tracking headers `x-session-id`, `x-user-id`, `x-device` also accepted.

**Request Payload (POST):**
```json
{
  "q": "shoes",
  "storeView": "en",
  "limit": 5,
  "suggestion": true,
  "category": true,
  "brand": true,
  "sessionId": "sess_abc123"
}
```

## 4. GraphQL Gateway (`/graphql`)
NexorAIQ exposes a unified GraphQL gateway for querying and managing search catalogs.

### Sample GraphQL Query:
```graphql
query SearchCatalog($query: String!, $perPage: Int) {
  searchCatalog(query: $query, perPage: $perPage) {
    total_found
    search_time_ms
    hits {
      id
      sku
      name
      price
      category
      is_pinned
      pinned_position
    }
  }
}
```

### Sample GraphQL Mutation:
```graphql
mutation LogEvent($sessionId: String!, $eventType: EventType!, $productId: String) {
  logEvent(sessionId: $sessionId, eventType: $eventType, productId: $productId) {
    id
    responseId
    eventType
    createdAt
  }
}
```

---

## 5. Web Resources & Links
- [REST API Reference](https://docs.nexoraiq.tech/): Interactive documentation with request tester.
- [GraphQL Explorer](https://docs.nexoraiq.tech/graphql): Visual schema browser and test IDE.
- [System Status](https://status.nexoraiq.tech/): Real-time uptime telemetry.
- [Platform Dashboard](https://app.nexoraiq.tech/): Manage API credentials and cluster settings.