# Littledata Agency API

> Read-only HTTP API that lets an AI agent act on behalf of an agency user. The
> agent authenticates with a per-user `ldat_*` bearer token minted from the
> Littledata UI at `/agency/api-tokens`. Scope is limited to the shops the user
> owns; the token never authenticates non-GET requests.

The OpenAPI spec is the machine-readable source of truth. The narrative guide
explains auth, token lifecycle, and error semantics in prose.

## Primary

- [OpenAPI 3.1 spec](./openapi.yaml): Machine-readable spec for every agency endpoint and schema.
- [Agency API guide](./AGENCY_API.md): Narrative documentation — auth, endpoints, errors, token lifecycle.

## Optional

- [Value metrics glossary](./VALUE_METRICS_GLOSSARY.md): Field definitions for the `valueMetrics` block on `GET /agency/customers/{shopName}`.

## Littledata staff only

The internal customer-success surface behind cip.littledata.io. It needs a token minted from a
Littledata **admin** session; an agency token gets 401 on every path below, so an agent holding
one should ignore this section.

- [CIP OpenAPI 3.1 spec](./openapi-cip.yaml): Every `/customers*` endpoint — list filters, detail, contacts, people, company, health history, notes, and the write endpoints (account owner, health flags, notes, champion, LinkedIn).
- [CIP contract](./CIP_DASHBOARD_CONTRACT.md): Field-by-field meaning, the `write` token scope and how to mint it, and the client-side segment rules (account-size bar, renewals window, installed-not-paying, recent churn) an agent must reproduce to agree with the dashboard.