# Portiko.ai — LLM Site Index

> Portiko is an **Agentic Commerce Gateway** that transforms storefronts into AI-native destinations. It identifies and grades commerce traffic from AI agents in real time, exposing catalogs as standardized MCP tools while providing traffic identity, response shaping, and human-in-the-loop governance controls.

## Site Map

### Homepage
- URL: https://dev.portiko.ai/
- Summary: Main landing page. Explains Portiko's four core pillars: Native MCP Endpoints, Traffic Identity, Response Shaping, and Governance.

### Features

#### Native MCP Endpoints
- URL: https://dev.portiko.ai/features/mcp/
- Summary: How Portiko exposes a storefront catalog as Model Context Protocol (MCP) tools. Includes the full `search_products` JSON schema, additional available tools (`get_product_detail`, `check_availability`, `get_catalog_categories`, `add_to_cart`), an example tool response, and the architecture for hosting an MCP endpoint.

#### Traffic Identity
- URL: https://dev.portiko.ai/features/identity/
- Summary: How Portiko classifies every inbound request using an Intent Score (0–100) into traffic classes: Authenticated Agent, High-Intent Anonymous, Ambiguous/Research, Low-Value Bot, or Threat. Signal sources include MCP protocol handshake, OAuth client credentials, behavioral patterns, IP/ASN reputation, and request cadence. Includes the `X-Portiko-Identity` header schema injected into backend requests.

#### Response Shaping
- URL: https://dev.portiko.ai/features/shaping/
- Summary: How Portiko prevents agentic load spikes using Token Bucket rate limiting (bucket sizes and refill rates per traffic class), semantic deduplication (cosine similarity > 0.92 within a session), and graceful degradation across 4 response fidelity levels. Includes the 429 rate limit response format with `Retry-After` header.

#### Governance
- URL: https://dev.portiko.ai/features/governance/
- Summary: How partners define rules for controlling agent actions — pausing high-value cart requests for human approval, blocking bulk account creation, requiring authentication for checkout. Includes the JSON governance rule DSL, audit log schema, and a list of Partner Dashboard monitoring capabilities.

### Conversion Pages

#### Request Partner Access (Retailers & Storefronts)
- URL: https://dev.portiko.ai/request-demo/
- Summary: Request form for retail partners who want to integrate Portiko into their storefront.

#### Developer Registration (Bot Builders & AI Agents)
- URL: https://dev.portiko.ai/bot-signup/
- Summary: Registration form for developers building AI shopping agents that connect to Portiko-powered storefronts.

#### Pricing
- URL: https://dev.portiko.ai/pricing/
- Summary: Pricing tiers and plans for Portiko partner integrations.

### Legal
- Privacy Policy: https://dev.portiko.ai/privacy/
- Terms of Service: https://dev.portiko.ai/terms/

### Technical Resources
- Sitemap: https://dev.portiko.ai/sitemap.xml
- Robots: https://dev.portiko.ai/robots.txt
- LLM Site Index (this file): https://dev.portiko.ai/llms.txt
- OpenAPI Spec: https://dev.portiko.ai/openapi.json

## Public API Endpoints

All endpoints are served by the Portiko `catalog-service`.

### Chat (used by the "Ask about products" widget)
- **POST** `/api/catalog/chat`
- Purpose: Conversational product search. The LLM interprets a natural language message, calls the catalog search internally, and returns a structured response with products and a follow-up question.
- Request body:
  ```json
  {
    "message": "oak dining table under $800",
    "history": [
      { "role": "user", "text": "..." },
      { "role": "assistant", "text": "..." }
    ]
  }
  ```
- Headers: `X-Session-Id: <uuid>` (for session continuity)
- Response:
  ```json
  {
    "message": "Here are some options...",
    "products": [ { "id": "...", "name": "...", "price": 649.00, "in_stock": true, "rating": 4.7 } ],
    "follow_up_question": "Would you like to filter by seating capacity?"
  }
  ```

### Product Search (direct)
- **GET** `/api/catalog/search?q={query}&max_price={usd}&limit={n}`
- **POST** `/api/catalog/search` with JSON body `{ "query": "...", "max_price": 800, "limit": 5 }`
- Purpose: Direct structured product search without LLM orchestration.

### Product Detail
- **GET** `/api/catalog/products/{id}`
- Purpose: Fetch full product details by SKU or product ID.

### OpenAPI Specification
- **GET** `/openapi.json`
- Purpose: Machine-readable OpenAPI 3.0 spec for all catalog-service endpoints.

## Key Technical Facts for Agents

- **Chat Endpoint**: `POST /api/catalog/chat` (natural language, session-aware)
- **Search Endpoint**: `GET /api/catalog/search?q=...` (structured, direct)
- **Product Detail**: `GET /api/catalog/products/{id}`
- **OpenAPI Spec**: `GET /openapi.json`


## Gated / Authenticated Areas (Not Publicly Crawlable)

- Partner Dashboard: https://dev.portiko.ai/portal/login (requires partner credentials)
- Developer Console: https://dev.portiko.ai/portal/bot-login (requires developer credentials)