# Salty

> Salty is a developer-first CRM (Customer Relationship Management) built for AI agents. It exposes a clean REST API, a Model Context Protocol (MCP) server, a CLI, and signed webhooks — no dashboards, no integration marketplace. Your AI agent does the work; Salty is the database underneath.

Salty is the inverse of every traditional CRM (HubSpot, Salesforce, Attio) that was built for humans first and bolted AI on later. Salty's primary interface is the API. Pricing is per API call, not per seat. Schema is extensible at runtime via `add_attribute` — no migrations, no service restarts.

The native object types are `person`, `company`, `deal`, `note`, `task`, `activity`, plus user-defined `custom_objects`. Every native object has `id` (uuid), `created_at`/`updated_at` (ISO-8601), and `custom_attributes` (JSON, lazily validated by the schema engine).

## Get started

- [Introduction](https://docs.trysalty.com/introduction): What Salty is, what ships in v1, hosts at a glance, three ways to call the API.
- [Quickstart](https://docs.trysalty.com/quickstart): Sign up, get a key, create a person, declare a custom attribute, watch validation reject a bad value — all in 60 seconds.
- [FAQ](https://docs.trysalty.com/faq): How Salty compares to HubSpot/Attio, can humans use it, what counts as an API call, can I export data, self-hosting, cap behavior, multi-agent, rate limits, webhook reliability.

## Use cases

- [AI Sales BDR](https://docs.trysalty.com/use-cases/sales-bdr): An AI sales-development-rep agent researches prospects, logs outreach, and tracks deal stage. End-to-end recipe with MCP prompts + REST equivalents.
- [AI Customer Success](https://docs.trysalty.com/use-cases/customer-success): An AI customer-success agent tracks accounts, logs touchpoints, scores account health, and flags churn risk.
- [AI Personal CRM](https://docs.trysalty.com/use-cases/personal-crm): An AI-powered personal CRM tracks your network, logs conversations, and surfaces relationships before you forget them.

## Concepts

- [Authentication](https://docs.trysalty.com/concepts/authentication): Three bearer-token paths (`sk_live_…` API keys, `salty_oat_…` OAuth tokens, Supabase JWTs) through one middleware. `c.var.authKind` distinguishes; usage cap meters agent traffic and exempts admin.
- [Errors](https://docs.trysalty.com/concepts/errors): Stripe-shaped error envelope with `type`, `code`, `message`, `param`. Every error has a stable code agents can switch on.
- [Pagination](https://docs.trysalty.com/concepts/pagination): Cursor-based. Pass `next_cursor` from response back as the `cursor` query param.
- [Idempotency](https://docs.trysalty.com/concepts/idempotency): `Idempotency-Key` header on POSTs. 24h replay safety. Mismatched body with same key returns 422.
- [Rate limits](https://docs.trysalty.com/concepts/rate-limits): Postgres token-bucket. Free 10 rps / 50 burst; Solo 100 / 500; Pro 1k / 5k. Headers: `X-RateLimit-*`. On 429, `Retry-After` is set.
- [Billing](https://docs.trysalty.com/concepts/billing): Three tiers (Free / Solo / Pro). Per-month API-call caps with $1/10k overage. Records overage at $0.50/1k. Configurable `hard_cap_api_calls` per workspace.
- [Schema engine](https://docs.trysalty.com/concepts/schema-engine): Lenient validation — defined keys validated, unknown keys pass through. Required attrs ARE enforced. Soft delete via `deprecated_at`. `data_type` frozen after creation; enums are append-only.
- [Observability](https://docs.trysalty.com/concepts/observability): Sentry + PostHog + Axiom + Better Stack — env-gated, ship dark. Light up by setting `SENTRY_DSN` / `POSTHOG_API_KEY` / `AXIOM_TOKEN`.
- [REST vs MCP vs CLI](https://docs.trysalty.com/concepts/surfaces): Decision matrix for which surface to use when. Common workflows mapped to each.

## API reference

- [Introduction](https://docs.trysalty.com/api-reference/introduction): Conventions — base URL, auth header, error envelope, pagination, expand parameter, idempotency.
- [Workspace](https://docs.trysalty.com/api-reference/workspace): GET workspace, GET usage, GET usage-logs, PATCH settings.
- [API keys](https://docs.trysalty.com/api-reference/api-keys): Create, list, revoke. Full key shown once; argon2-hashed at rest.
- [People](https://docs.trysalty.com/api-reference/people): List, get, create, patch, delete. Filter by email/domain. Search endpoint.
- [Companies](https://docs.trysalty.com/api-reference/companies): List, get, create, patch, delete. Filter by domain.
- [Deals](https://docs.trysalty.com/api-reference/deals): List, create, patch, delete. `value_cents` is **string-encoded bigint**.
- [Notes, Tasks, Activities](https://docs.trysalty.com/api-reference/notes): Attach to person/company/deal via `parent_object_type` + `parent_object_id`.
- [Schema](https://docs.trysalty.com/api-reference/schema): GET schema, POST attribute, PATCH attribute (metadata + append-only enums), DELETE attribute (soft, sets `deprecated_at`).
- [Custom Objects](https://docs.trysalty.com/api-reference/custom-objects): Define custom object types and create records.

## MCP server

- [MCP introduction](https://docs.trysalty.com/mcp/introduction): Streamable HTTP transport at `https://mcp.trysalty.com/mcp`. OAuth 2.1 + PKCE. 15 tools curated for context efficiency.
- [Agent guide](https://docs.trysalty.com/mcp/agent-guide): Canonical operating manual injected as MCP server `instructions` on `initialize`. Tool catalog, 8 hard rules (no delete tools, `value_cents` is string, parent uses `parent_object_type`, etc.), 5 workflow recipes, error→recovery table.

## CLI

- [CLI introduction](https://docs.trysalty.com/cli/introduction): `salty login` browser OAuth, OS keychain. Commands: `whoami`, `keys`, `people`, `schema`, `webhooks`, `usage`, `logs tail`. Install via `npm i -g salty-cli` (Phase 6f).

## Webhooks

- [Webhooks](https://docs.trysalty.com/webhooks/introduction): HMAC-SHA-256 signed (`Salty-Signature: t=<ms>,v1=<hex>`). 8-attempt exponential backoff (1s → 5s → 30s → 5min → 30min → 2h → 12h). Auto-deactivate on 8 fails + meta-event fans out to other endpoints.

## Optional

- [GitHub](https://github.com/trysalty/salty): Source repo (closed for v1; SDK + CLI are MIT-licensed).
- [AGENTS.md](https://github.com/trysalty/salty/blob/main/AGENTS.md): The agent operating manual — same content as the MCP `instructions` field, formatted for non-MCP agent frameworks (Codex, OpenAI Agents SDK, Claude Code).
- [Status](https://docs.trysalty.com/status): Self-hosted status page polling `/healthz` on api/mcp/web every 30s.