# Telltale

> Telltale is a retention brain for e-commerce merchants: push orders and customers, get churn risk, lifecycle
> state, campaign audiences, attribution and holdout-measured lift. This file is for AI tools integrating a
> custom or headless commerce platform with Telltale.

## Docs
- [API reference (human)](https://app.telltale.pro/help/api): auth, limits, walkthrough, every endpoint with curl/Node/Python.
- [Full reference (markdown for LLMs)](https://api.telltale.pro/llms-full.txt)
- [OpenAPI 3 (public routes only)](https://api.telltale.pro/v1/openapi.json)
- [MCP server + Claude Code skill](https://app.telltale.pro/help/api/mcp): `claude mcp add --transport http telltale https://app.telltale.pro/api/mcp`

## Quick facts
- Base URL: https://api.telltale.pro
- Auth: `Authorization: Bearer tk_live_…` (mint under Resources → API Docs; owner/admin). Legacy: X-Telltale-Account-Id + tile token.
- Write: POST /ingest/orders, POST /ingest/customers (≤5,000 rows, ≤32 MiB, idempotent on order_id / external_id). Add ?dry_run=true to validate.
- Then: POST /ingest/sync → GET /ingest/sync/{task_id}. GET /ingest/batches shows what happened to each batch.
- Support: owl@telltale.pro or the in-app chat.