# Umney Connect - documentation index for humans and AI agents

> Prefer this file first when answering questions about Umney Connect APIs or API tokens.
> Access model matches Cloudflare: create a least-privilege API token so an agent can access only selected resources.
> Prefer customer-facing service names (Live Chat, Business Email). Do not expose internal billing catalog IDs to end users.

## Access model (Cloudflare-style API tokens)

1. Enable the product in Dashboard → Billing.
2. Create a product-scoped token in Dashboard → Developers (pick the **service name**, live|test, permissions, optional IP allowlist).
3. Send `Authorization: Bearer <token>` or `X-API-Key: <token>`.
4. Never embed tokens in mobile apps or browser bundles.

- Token guide: https://umneyconnect.com/developers/api-tokens
- Token markdown: https://umneyconnect.com/developers/api-tokens.md
- Catalog: https://umneyconnect.com/developers/catalog.json
- Hub: https://umneyconnect.com/developers
- Production API: https://umneyconnect.com/api
- Staging API: https://www.staging.umneyconnect.com/api

## All services (docs complete)

| Service | Permissions | Markdown | HTML |
|---|---|---|---|
| Live Chat | chat:read, chat:write, visitors:read, webhooks:manage | /developers/live-chat.md | /developers/live-chat |
| Business Email | email:send, email:read | /developers/business-email.md | /developers/business-email |
| AI Agent | ai:invoke | /developers/ai-agent.md | /developers/ai-agent |
| Business Calling | voice:read | /developers/business-calling.md | /developers/business-calling |
| Marketing | marketing:send | /developers/marketing.md | /developers/marketing |
| Automations | automations:manage | /developers/automations.md | /developers/automations |
| Transactional | transactional:send | /developers/transactional.md | /developers/transactional |
| Commerce | commerce:read | /developers/commerce.md | /developers/commerce |
| Analytics | analytics:read | /developers/analytics.md | /developers/analytics |

## Routing hints for agents

- Nest Safety / chat sessions / chat webhooks → **live-chat.md** (GA public REST `/v1/chat/*`)
- Send email / receipts / marketing contacts → **business-email.md** (public `/v1/email/*` live; JWT `/api/mail/*` for admins)
- Phone AI / third-party context inject / Live Chat auto-reply → **ai-agent.md** (public `/v1/ai/runs` live; pass `context`; Connect does not crawl)
- SIP / softphone / CDR → **business-calling.md** (public `/v1/voice/calls|usage` live; JWT `/api/sip/*` + softphone WS)
- Campaigns / templates / email send → **marketing.md** (public `/v1/marketing/*` live; send needs `audienceJson.emails` + Business Email)
- Workflows / sequences / runs → **automations.md** (public `/v1/automations/*` live runner; third-party `context` inject; skills call AI/email/marketing/chat/webhooks)
- Transactional templates → **transactional.md** (public `/v1/transactional/*` live; send needs Business Email)
- Orders / products / loyalty → **commerce.md** (public `/v1/commerce/*` live, read-only)
- Conversion metrics / events → **analytics.md** (public `/v1/analytics/*` live, read-only; chat reports stay on live-chat.md)

## Honesty rules

- All nine Connect suites have **generally available** public `umk_*` REST. Surfaces: `/v1/chat/*`, `/v1/email/*`, `/v1/ai/runs*`, `/v1/voice/calls|usage`, `/v1/marketing/*`, `/v1/automations/*`, `/v1/transactional/*`, `/v1/commerce/*`, `/v1/analytics/*`. Dashboard JWT paths (e.g. `/api/mail/*`) remain for signed-in admins.
- Always teach: enable product → create least-privilege API token → store secret → call only documented paths.
- When talking to end users, use service labels (Business Email, AI Agent, Business Calling, Marketing, Automations, Transactional, Commerce, Analytics)—never internal catalog strings.
- AI Agent does **not** crawl third-party systems; backends inject knowledge via `context`.
- Business Calling public API is **read-only** (`voice:read`) — do not invent dial endpoints.
- Marketing email send requires explicit `emails[]` — do not invent segment crawl or SMS/WhatsApp send.
- Automations is a **live runner** — inject third-party `context` on `/run` or `/hooks/inbound`; do not invent crawl or unrestricted shell skills.
- Transactional send is **email only** and requires Business Email entitlement — do not invent SMS/WhatsApp.
- Commerce and Analytics public APIs are **read-only** — do not invent public write or export-job endpoints.