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

# REST API

> Read and write directory, CRM, context, and prospecting data over a token-authenticated REST API.

The ECN REST API is a token-authenticated JSON API under `/api/v1/`. The full,
always-current endpoint reference is generated from the backend's OpenAPI schema and
listed under **Endpoints** in the sidebar.

## Base URLs

| Environment | Base URL                                |
| ----------- | --------------------------------------- |
| Production  | `https://earthcare.network/api/v1`      |
| Test        | `https://test.earthcare.network/api/v1` |
| Local       | `http://localhost:8000/api/v1`          |

## Authentication

Send a DRF token on every request. See [Authentication](/get-started/authentication).

```bash theme={null}
curl https://earthcare.network/api/v1/auth/me/ \
  -H "Authorization: Token 9a8b7c…"
```

Public read endpoints (directory search, public profiles) work without a token;
workspace endpoints require one.

<Warning>
  **Workspace (org-scoped) endpoints require an `organization_id`.** CRM
  (`/crm/*`), GTM (`/gtm/*`), automation (`/automation/*`), credits
  (`/credits/wallet|transactions|usage`), and MCP-key management all need it —
  as a **query param** on reads (and on most writes; some writes also accept it
  in the body). Omitting it returns `400` or an empty result, not your data. Get
  your org UUID from `GET /auth/me/` → `organizations[].id`.
</Warning>

## Conventions

* **JSON in, JSON out.** Send `Content-Type: application/json`.
* **UUIDs** identify most resources.
* **Errors** use standard HTTP status codes with a JSON body describing the problem
  (`400` validation, `401` unauthenticated, `403` forbidden / cross-tenant, `404`
  not found, `402` over budget / insufficient credits, `429` rate limited).
* **Pagination** on list endpoints returns `count`, `next`, `previous`, `results`.

## Headline endpoint groups

| Group             | Prefix                                   | Highlights                                   |
| ----------------- | ---------------------------------------- | -------------------------------------------- |
| Auth & account    | `/auth/`, `/me/`                         | login, register, profile                     |
| Directory         | `/businesses/`, `/networks/`, `/search/` | search, profiles, relationships              |
| Context           | `/context/`, `/business-context/`        | Context Packs, modules                       |
| CRM               | `/crm/`                                  | contacts, accounts, deals, tasks, forms      |
| AI                | `/ai/`                                   | metered run, estimate, agent stream, threads |
| Credits           | `/credits/`                              | wallet, rate cards, transactions, usage      |
| GTM / prospecting | `/gtm/`                                  | profiles, discover-leads, draft-emails       |
| Automation        | `/automation/`                           | workflows, runs, enrollments                 |
| MCP keys          | `/mcp/keys/`                             | create / revoke MCP API keys                 |

<Note>
  The **Endpoints** pages render from an OpenAPI 3 spec. Today that spec is
  **curated** — accurate paths, methods, auth, and representative bodies for the
  headline endpoints — because most ECN views are function-based and don't yet
  expose serializers for full auto-generation. The drf-spectacular tooling is wired
  (`manage.py spectacular --settings ecn.settings_docs`) and takes over automatically
  as the v2 refactor migrates views to serializer-backed generics. Either way, the
  spec is re-synced to `test` each docs iteration.
</Note>