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

# Self-hosted CRM API

> REST API for contacts, companies, deals, tasks, notes, and custom objects on your own BasicsOS server.

The Self-hosted CRM API is the HTTP interface to the CRM built into every BasicsOS server deployment. Use it to manage contacts, companies, deals, tasks, notes, and custom objects from any language or tool that speaks HTTP.

> [!NOTE]
>
> **This is not the Basics Gateway API.** The gateway (`api.basicsos.com`) handles chat, embeddings, audio, and email. These CRM endpoints run on **your** server — the same origin where the BasicsOS web app is hosted (e.g. `https://your-app.up.railway.app`). For AI and voice features, see the [Basics Gateway API docs](https://basicsos.com/docs/api-reference/introduction.md). Your server communicates with the gateway internally using the configured `BASICSOS_API_URL`.

## Base URL

The base URL is your deployment's origin. There is no shared cloud endpoint for CRM data.

| Environment | Base URL |
| - | - |
| Railway (example) | `https://your-app.up.railway.app` |
| Custom domain | `https://crm.yourcompany.com` |
| Local development | `http://localhost:3000` |

All paths in this section are relative to your base URL.

## What you can do

| Area | Description |
| - | - |
| **Contacts & companies** | Create, list, update, delete, and merge contacts and companies. |
| **Deals** | Manage deal records through pipeline stages. |
| **Tasks** | Create and track tasks linked to contacts, companies, or deals. |
| **Notes** | Attach notes to contacts, deals, and companies. |
| **Tags** | Organize records with tags. |
| **Custom objects** | Work with any custom CRM object your organization defines. |
| **Automation rules** | Read and manage CRM automation configurations. |
| **Schema introspection** | Discover fields, types, and object definitions at runtime. |

## Quick example

```bash theme={null}
# List the first 25 contacts
curl https://your-app.up.railway.app/api/contacts \
  -H "Authorization: Bearer bos_crm_your_token_here"
```

```bash theme={null}
# Create a new contact
curl -X POST https://your-app.up.railway.app/api/contacts \
  -H "Authorization: Bearer bos_crm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  }'
```

## Next steps

> **[Authentication](https://basicsos.com/docs/self-hosted-crm/authentication.md)**
>
> Session cookies, Bearer tokens, and Personal CRM API tokens.

> **[CRM REST API](https://basicsos.com/docs/self-hosted-crm/crm-rest-api.md)**
>
> Full CRUD reference for every resource type.

> **[Related APIs](https://basicsos.com/docs/self-hosted-crm/related-apis.md)**
>
> Schema introspection, views, custom fields, and more.

> **[Errors & CORS](https://basicsos.com/docs/self-hosted-crm/errors-and-cors.md)**
>
> Status codes, error shapes, and cross-origin setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.