> ## Documentation Index
> Fetch the complete documentation index at: https://trysalty.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Conventions, base URL, error envelope, links.

This is the REST API reference for [Salty](https://trysalty.com), the CRM built for AI agents — see [trysalty.com](https://trysalty.com) for the product overview and pricing.

Every curl example below uses `$SALTY_API` as the base URL — set it once and the snippets work as-is.

```bash theme={null}
export SALTY_API=https://api.trysalty.com
```

All requests require `Authorization: Bearer <token>` (an `sk_live_…` API key, a Supabase JWT, or a `salty_oat_…` OAuth token). See [Authentication](/docs/concepts/authentication).

## Conventions

* **Identifiers** are UUIDs unless noted.
* **Timestamps** are ISO 8601 strings (`2026-05-24T02:45:46.461Z`).
* **bigint** fields (`deals.value_cents`) are returned as **strings** to avoid JS precision loss.
* **All errors** use the Stripe-shaped envelope. See [Errors](/docs/concepts/errors).
* **Pagination** uses opaque cursors. See [Pagination](/docs/concepts/pagination).
* **POST is idempotent** when you pass `Idempotency-Key`. See [Idempotency](/docs/concepts/idempotency).
* **Rate limits** are per workspace, per plan tier. See [Rate limits](/docs/concepts/rate-limits).
* **Custom attributes** are validated by the schema engine. See [Schema engine](/docs/concepts/schema-engine).

## Interactive explorer

Every endpoint listed here is also available in the **Scalar API explorer** at `$SALTY_API/reference`. Paste your key, click an endpoint, send a request, see the real response.

## Endpoints in v1

| Group                                           | Endpoints                                                    |
| ----------------------------------------------- | ------------------------------------------------------------ |
| [Workspace](/docs/api-reference/workspace)           | `GET /workspace`, `GET /workspace/usage`, `PATCH /workspace` |
| [API keys](/docs/api-reference/api-keys)             | `GET /api-keys`, `POST /api-keys`, `DELETE /api-keys/:id`    |
| [People](/docs/api-reference/people)                 | CRUD + `POST /people/search` + `?expand=primary_company`     |
| [Companies](/docs/api-reference/companies)           | CRUD                                                         |
| [Deals](/docs/api-reference/deals)                   | CRUD + `?expand=primary_company,primary_person`              |
| [Notes](/docs/api-reference/notes)                   | CRUD (parent must be person/company/deal)                    |
| [Tasks](/docs/api-reference/tasks)                   | CRUD (parent optional)                                       |
| [Activities](/docs/api-reference/activities)         | CRUD (parent + `occurred_at` required)                       |
| [Schema](/docs/api-reference/schema)                 | Declare/modify/deprecate attribute definitions               |
| [Custom Objects](/docs/api-reference/custom-objects) | Define new object types + records                            |

Deletes are soft — records move to a 30-day [trash](/docs/api-reference/trash) and can be restored.

## SDK alternative

Every endpoint here is also a method on the `Salty` class:

```ts theme={null}
import { Salty } from '@salty/sdk';
const salty = new Salty({ apiKey: process.env.SALTY_API_KEY! });

await salty.people.postPeople({ body: { email: 'jane@acme.com' } });
await salty.schema.getSchemaByObjectType({ path: { object_type: 'person' } });
```