# Customer-AI

> Customer-AI is a knowledge-retrieval platform that gives AI agents structured, operator-approved answers to customer questions, with full provenance and certainty labels.
> Every response is grounded in an operator-reviewed knowledge object, with its provenance returned alongside the answer.

## Platform overview

The full platform llms.txt (covering REST, MCP, and the Operator Console) is at: https://customer-ai.com/llms.txt

## What this API does

Customer-AI answers customer questions about services offered by operators — for example, utilities such as electricity networks — the same approach applies equally to operators in other regulated-service sectors — by retrieving
approved knowledge objects from a curated repository. Questions are automatically classified by journey
(e.g. compensation claims, complaints) and organisation, then answered with citations and certainty labels.

## Authentication

Include an `X-API-Key` header to scope requests to your organisation's knowledge.
Anonymous requests are also accepted and use the `organisation` body/query parameter instead.

## Base URL

https://customer-ai.com/api/v1/

## Key endpoints

- `POST https://customer-ai.com/api/v1/ask` — ask a natural-language customer question; returns a plain-language answer with provenance
- `GET  https://customer-ai.com/api/v1/ask?question=...` — same underlying answer as POST /ask, via GET query params (no credentials required; for web-browsing AI). Returns `text/plain` by default; send `Accept: application/json` for the structured response.
- `POST https://customer-ai.com/api/v1/scenario` — full scenario evaluation with classification, retrieved objects, outcomes, and gaps
- `GET  https://customer-ai.com/api/v1/knowledge` — search approved knowledge objects (filter by journey, jurisdiction, organisation, objectType; free-text `search` param)
- `GET  https://customer-ai.com/api/v1/knowledge/{logicalId}` — retrieve a single knowledge object by logical ID
- `GET  https://customer-ai.com/api/v1/journeys` — list supported customer journeys and valid journey keys
- `GET  https://customer-ai.com/api/v1/organisations` — list organisations with published content, accepted codes and aliases

## Interaction methods

Customer-AI supports four integration paths for AI assistants:

### 1. MCP (Claude.ai, Cursor, Claude Desktop, OpenAI Responses API, ChatGPT Developer Mode)

MCP endpoint: https://customer-ai.com/api/mcp
Transport: Streamable HTTP (stateless). No API key required for cross-org access; include X-API-Key to scope to an org.
Tools available: ask_question, run_scenario, search_knowledge, get_knowledge_object, get_source, list_journeys, list_organisations, list_classification_tags, submit_agent_feedback.
`ask_question`/`run_scenario` accept an optional `classificationTags` array ({tag, priority: suppress|enhance|boost}) that multiplies the ranking score of matching knowledge objects (defaults: boost ×3, enhance ×2, suppress ×0.5 — operators can tune these per journey) — never fully restricting which objects are eligible. Boosting the tags central to the scenario while suppressing known-noise tags is far more effective than boosting alone. Call `list_classification_tags` first to discover valid tag values.
This is the same MCP endpoint used by both Claude and OpenAI: point Claude's MCP connector, OpenAI's Responses API `mcp` tool (`server_url` + optional `authorization`), or a ChatGPT Developer Mode / Apps connector at this URL — no separate manifest is needed for MCP.

### 2. GET ask (Perplexity, ChatGPT browse mode, web-crawling agents)

Web-browsing AI assistants that can only fetch a URL via GET (no custom headers, no POST body) can use:
  https://customer-ai.com/api/v1/ask?question=My+power+went+out+during+a+storm+can+I+claim+compensation
Optional query params: journey, jurisdiction, organisation.
No API key required. Returns `text/plain` by default (ready to display, no JSON parsing needed); send `Accept: application/json` for the same structured response as POST /ask.

### 3. OpenAPI Actions (legacy Custom GPT Actions compatibility)

OpenAPI Actions schema: https://customer-ai.com/api/v1/openapi.json
Plugin manifest (ai-plugin.json, legacy format): https://customer-ai.com/.well-known/ai-plugin.json
For tooling that still consumes an OpenAPI Actions schema directly (e.g. a Custom GPT's Actions tab) rather than connecting over MCP. The ai-plugin.json manifest follows OpenAI's now-retired ChatGPT plugin store format — it is kept only as a compatibility shim for Actions tooling that still reads it, not as the recommended ChatGPT integration path. Prefer MCP (see above) for any client that supports it.
Supports both anonymous (cross-org) and X-API-Key authenticated requests.

## Machine-readable spec

Full OpenAPI 3.1 specification: https://customer-ai.com/api/v1/openapi.json
The spec is generated on first request and cached for a few minutes; it refreshes automatically after that, and immediately whenever the underlying schema changes — no restart needed.