# SIMOSphere AI · API surface

> Scoped llms.txt for the public API of simosphereai.com.
> For the full overview: https://simosphereai.com/llms.txt
> For the deep dive (auth, endpoints, examples): https://simosphereai.com/llms-full.txt

## Endpoints

- `POST /api/chat-completion.php` — public chat proxy, OpenAI-style chat completion shape, HMAC-bound session tokens for anti-bot, IP rate-limit (20/h). Forwards to the SIMO Gateway at `https://api.simosphereai.com/v1/chat/completions`.
- `POST /api/ask.php` — NLWeb-compatible natural-language ask endpoint with optional SSE streaming (events: start/token/result/complete). Wraps FAQ-quick-path + weather tool + LLM fallback.
- `GET  /api/ask.php` — capability discovery (returns schema, examples, streaming info).
- `POST /api/mcp.php` — WebMCP JSON-RPC 2.0 endpoint (MCP version 2025-06-18). Tools: ask_simosphere, list_models, get_pricing, faq_lookup, get_weather, get_company_info. Resources: 8 entries including KB-core, KB-full, pricing/table, faq/catalog, compliance/matrix, api/catalog, company/info, models/catalog.
- `GET  /api/mcp.php` — MCP server manifest discovery.
- `GET  /api/tools.php` — Function-calling tools in OpenAI / Anthropic / Mistral / Gemini formats. Use `?dialect=anthropic|gemini|openai` to switch.
- `POST /api/tools/call` — Execute a tool directly (no MCP runtime needed).
- `POST /api/jobs.php` — Submit an async job. Supports `Idempotency-Key` header (24h dedupe window). Types: ask, faq_lookup, kb_refresh.
- `GET  /api/jobs/{id}` — Poll a job's status. Lifecycle: queued → running → succeeded | failed | cancelled.
- `GET  /api/capabilities.php` — Aggregate capability index for AI agents (one fetch reveals every supported feature).
- `GET  /api/status.php` — IETF health-check format. Aliases: `/status`, `/.well-known/health`.
- `GET  /api/consulting.json` — public catalogue of consulting packages with prices.
- `GET  /api/training.json` — public catalogue of trainings.
- `GET  /api/hardware.json` — public catalogue of hardware offerings.
- `GET  /api/discovery-call.json` — booking metadata for the free 30-min discovery call.
- `GET  /api/site-meta.json` — agent-readable site metadata; also served at `/?mode=agent`.
- `POST /api/checkout.php` — Stripe-backed checkout for fixed-fee packages.
- `POST /api/subscribe.php` — newsletter / waitlist subscription.

## Authentication

- Public chat: ephemeral HMAC token, fetch via `GET /api/chat-completion.php?action=token`, then send as `X-Simo-Token` header on POST. Token bound to IP + User-Agent, valid 1 hour, minimum age 3 seconds (anti-bot).
- Platform (workspace) API: Bearer token (Authorization header), keys created at https://onboarding.simosphereai.com.

## Rate limits

- `/api/chat-completion.php`: 20 requests / hour / IP. Returns HTTP 429 with `Retry-After` and `next_steps` (account creation, discovery call, sprint links).
- `/api/ask.php`: same upstream gateway limits apply (30 req/min, 1.5M tokens/day on the marketing key).

## Versioning + Deprecation

- API-Version header on all endpoints: `2026-05-18`
- NLWeb-Version: `0.1`
- MCP-Version: `2025-06-18`
- Full versioning policy + 12-month sunset window: https://simosphereai.com/developers/api-versioning
- Deprecation + Sunset headers per RFC 8594 once an endpoint is marked.

## Error model + recovery

- Every 4xx/5xx response uses the same structured JSON envelope: `{"error": {"message", "type", "code", "retry_after"}}`.
- Idempotency-Key header supported on mutating endpoints (24h dedupe window). Replays return original response + `Idempotency-Replayed: true` header.
- Rate-limit headers per RFC 9598 (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`, `Retry-After`).
- Full retry-loop pseudocode + reconnect semantics: https://simosphereai.com/developers/error-recovery

## Discovery

- OpenAPI 3.1: https://simosphereai.com/openapi.json
- MCP manifest: https://simosphereai.com/.well-known/mcp/manifest.json
- MCP alt path: https://simosphereai.com/.well-known/mcp.json
- Capability index: https://simosphereai.com/api/capabilities.php
- API catalog (RFC 9727 linkset): https://simosphereai.com/.well-known/api-catalog
- A2A Agent card: https://simosphereai.com/.well-known/agent-card.json
- Agent skills index: https://simosphereai.com/.well-known/agent-skills/index.json
- AGENTS.md: https://simosphereai.com/AGENTS.md
- API versioning doc: https://simosphereai.com/developers/api-versioning
- Error recovery doc: https://simosphereai.com/developers/error-recovery

## Example: minimal chat call

```bash
# 1. Get a session token
TOKEN=$(curl -sS 'https://simosphereai.com/api/chat-completion.php?action=token' \
  -H 'Origin: https://simosphereai.com' | jq -r .token)

# 2. Send a chat message (wait 3+ seconds between token and call)
sleep 4
curl -sS -X POST 'https://simosphereai.com/api/chat-completion.php' \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://simosphereai.com' \
  -H "X-Simo-Token: $TOKEN" \
  -d "{
    \"message\": \"What does SIMOSphere AI cost?\",
    \"model\": \"swiss-ai/apertus-8b-instruct-2509\",
    \"mode\": \"online\",
    \"session_token\": \"$TOKEN\"
  }"
```

## Example: NLWeb ask call

```bash
curl -sS -X POST 'https://simosphereai.com/api/ask.php' \
  -H 'Content-Type: application/json' \
  -d '{"query": "Is SIMOSphere AI GDPR compliant?"}'
```

## Example: NLWeb streaming

```bash
curl -N -X POST 'https://simosphereai.com/api/ask.php' \
  -H 'Content-Type: application/json' \
  -H 'Prefer: streaming' \
  -H 'Accept: text/event-stream' \
  -d '{"query": "How fast can I go live?"}'
```

## Example: MCP JSON-RPC (list tools)

```bash
curl -sS -X POST 'https://simosphereai.com/api/mcp.php' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Example: function-call via /api/tools/call

```bash
curl -sS -X POST 'https://simosphereai.com/api/tools/call' \
  -H 'Content-Type: application/json' \
  -d '{"name":"get_pricing","arguments":{"category":"consulting"}}'
```

## Example: async job with idempotency

```bash
curl -sS -X POST 'https://simosphereai.com/api/jobs' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f7b1f5c-9c4e-4a3a-9ec2-ef2c5e3a8e80' \
  -d '{"type":"ask","input":{"query":"What is SIMOSphere AI?"}}'

# Poll the result
curl -sS 'https://simosphereai.com/api/jobs/job_abc123def4567890'
```

## Example: fetch full capability index

```bash
curl -sS 'https://simosphereai.com/api/capabilities.php' | jq .capabilities
```