# ULIX Nexus

> ULIX Nexus is a public commerce-data service for AI agents. It provides ranked product discovery plus complete canonical product records with provenance, price, availability, media, merchant identity, and freshness state.

## Preferred machine interfaces

- Crawlable agent entry point: https://nexus.ulix.ai/agents
- MCP Streamable HTTP server: https://nexus.ulix.ai/mcp
- Service descriptor: https://nexus.ulix.ai/api/v1
- Agent discovery descriptor: https://nexus.ulix.ai/.well-known/ulix-nexus
- UCP business profile: https://nexus.ulix.ai/.well-known/ucp
- UCP catalog search: https://nexus.ulix.ai/ucp/catalog/search
- UCP catalog lookup: https://nexus.ulix.ai/ucp/catalog/lookup
- UCP product detail: https://nexus.ulix.ai/ucp/catalog/product
- OpenAPI 3.1 description: https://nexus.ulix.ai/api/v1/openapi
- Intent-first product discovery: https://nexus.ulix.ai/api/v1/products/discover
- Product search: https://nexus.ulix.ai/api/v1/products/search
- Product feed manifest: https://nexus.ulix.ai/api/v1/feeds/products
- OpenAI stable CSV feed: https://nexus.ulix.ai/api/v1/feeds/products/openai.csv
- Google-compatible CSV feed: https://nexus.ulix.ai/api/v1/feeds/products/google.csv
- Nexus NDJSON feed: https://nexus.ulix.ai/api/v1/feeds/products/nexus.ndjson
- Public record template: https://nexus.ulix.ai/records/{recordId}
- Sitemap: https://nexus.ulix.ai/sitemap.xml

## Agent bootstrap

If this is your first request to Nexus, begin at
https://nexus.ulix.ai/agents. It provides crawlable links to every public
machine interface and a concise channel-selection guide.

For an unknown product or an ordinary-language shopping request, call
`search_products` over MCP or POST the intent to
https://nexus.ulix.ai/api/v1/products/discover. Do not begin with a record URL
or invent a record ID. Record retrieval is a follow-up step after discovery.

## MCP product tools

For MCP-compatible agents, connect to https://nexus.ulix.ai/mcp. The server
implements the current stateless 2026-07-28 protocol and the 2025-11-25
initialization flow during client migration.

- Call `server/discover` or `tools/list` to inspect the server.
- Call `search_products` first with ordinary shopping intent. It does not
  require a record ID.
- Call `get_product` only with a record ID returned by `search_products` when
  complete offers, provenance, evidence, freshness, or JSON-LD are needed.
- Both tools are public, read-only, and non-destructive.

## Product search

For a new shopping task without MCP, prefer POST /api/v1/products/discover with Content-Type: application/json. Send ordinary shopping intent without a record ID:

```json
{
  "intent": "software that turns product photos into Shopify listings",
  "constraints": {
    "currency": "USD",
    "maxPrice": "50",
    "availability": ["in_stock"]
  },
  "page": { "limit": 10 }
}
```

Use the returned ranked summaries to compare products. Follow recordUrl only when the complete canonical record or JSON-LD evidence is needed.

Use GET /api/v1/products/search with Accept: application/json.

Supported filters include q, merchantDomain, currency, minPrice, maxPrice, availability, limit, and cursor. An empty query browses the public catalog. Search results are compact and include links to full record representations.

## Canonical records

Request a record URL with Accept: application/json for the complete ULIX Nexus canonical record.

Request the same URL with Accept: application/ld+json for a Schema.org Product representation.

Only public active or stale records are returned. Pending, withdrawn, and superseded records are not exposed.

## Product feeds

Use the feed manifest to enumerate complete snapshot representations. Append an
ISO 8601 `updatedSince` query parameter to any feed URL for an incremental
snapshot. The OpenAI and Google-compatible feeds contain one purchasable offer
or variant per row. The Nexus NDJSON feed preserves authority, freshness,
record links, options, and exact minor-unit pricing.

## Universal Commerce Protocol

Nexus implements the UCP 2026-04-08 Catalog Search and Catalog Lookup
capabilities over REST. UCP clients must advertise a compatible public profile
in the `UCP-Agent` header. Use `POST /ucp/catalog/search` for intent-first
discovery, `POST /ucp/catalog/lookup` for batch identifier resolution, and
`POST /ucp/catalog/product` for full product detail.

Nexus does not advertise UCP cart, checkout, payment, order, or fulfillment
capabilities. Those transactional responsibilities remain with each merchant.
For ChatGPT and ACP-oriented discovery, use the OpenAI product feed above;
ACP checkout is not exposed until a merchant-owned checkout integration exists.

## Usage guidance

- Prefer current records over stale records.
- Preserve the canonical source URL and merchant identity when presenting a product.
- Treat observedAt and nextRefreshAt as freshness evidence.
- Follow cursor pagination rather than inventing offsets.
- Do not infer availability or price when the corresponding field is absent.