Skip to content

A full-featured CRM built with React, shadcn/ui, and Supabase.

Rewrite API Doc

fzaninottobd040935a43d
diff --git a/doc/src/content/docs/developers/atomic-crm-api.mdx b/doc/src/content/docs/developers/atomic-crm-api.mdx
index 295afcf4..1cbd5782 100644
--- a/doc/src/content/docs/developers/atomic-crm-api.mdx
+++ b/doc/src/content/docs/developers/atomic-crm-api.mdx
@@ -1,12 +1,16 @@
---
-title: Atomic CRM API
+title: REST API
description: This document explains how to use the Atomic CRM API outside of the Supabase data provider.
---
-This document explains how to use the Atomic CRM API outside of Atomic CRM.
-The API is built on top of Supabase, that is itself built on top of Postgrest.
-This means it is a REST API so it can be called from any programming language that can make HTTP requests.
-See the [Supabase documentation](https://supabase.com/docs/guides/api) for more details.
+Atomic CRM exposes a complete REST API that lets you do everything you can do with the CRM.
+The API is built on top of [Supabase](https://supabase.com/docs/guides/api), that is itself built on top of [Postgrest](https://docs.postgrest.org/en/latest/).
+
+## Instance API Doc In Studio
+
+Use the Supabase Studio to see the [automatically generated documentation](https://supabase.com/dashboard/project/_/api) for your Atomic CRM instance. It lists all the available endpoints and their parameters. This page explains how to call each endpoint either with the supabase client, or bash (curl).
+
+![Supabase API documentation](../../images/apiDocumentation.png)
## Authentication
@@ -14,11 +18,11 @@ To call the API, you need to pass an `apikey` in the headers of your requests. T
![Supabase API key](../../images/supabaseApiKey.png)
-You have two types of API keys in Supabase: the publishable API key, and the secret API key. You should use the publishable API key to call the API from your frontend or from any client side code, as it has limited permissions and does not allow to bypass RLS policies.
+You have two types of API keys in Supabase: the **publishable** API key, and the **secret** API key. You should use the publishable API key to call the API from your frontend or from any client side code, as it has limited permissions and does not allow to bypass RLS policies.
You should never use the secret API key in client side code, as it gives full access to your database and can be easily extracted from your code.
Only use the secret API key server side, and be sure to handle all authentication and security yourself if you go this way.
-When calling protected endpoints with the publishable API key, You also need to authenticate the user and get a JWT token to be able to call the API.
+When calling protected endpoints with the publishable API key, you also need to authenticate the user and get a JWT token to be able to call the API.
Use the `/auth/v1/token` endpoint to authenticate a user and get a JWT token. You need to pass the user's email and password in the body of the request.
@@ -45,75 +49,82 @@ curl -X GET 'https://<instance_url>/rest/v1/contacts' \
-H 'Authorization: Bearer <your_jwt_token>'
```
+## OpenAPI Specification
-## API Endpoints
+The API exposes an OpenAPI specification. You need to use your API key to access it:
-The API endpoints are generated from the database schema.
+```sh
+curl https://<instance_url>/rest/v1/ \
+ -H 'apikey: <your_publishable_api_key>' \
+ -H 'Authorization: Bearer <your_jwt_token>'
+```
-You can see the [automatically generated documentation](https://supabase.com/dashboard/project/_/api) for your Atomic CRM Supabase project to see all the available endpoints and their parameters.
-You can see how to call each endpoint either with the supabase client, or bash (curl).
+You can customize the OpenAPI specification via comments on tables. See the [Postgrest documentation](https://docs.postgrest.org/en/v14/references/api/openapi.html#openapi) for more details.
-![Supabase API documentation](../../images/apiDocumentation.png)
+## Auth API Endpoints
-As a quick preview here is a list of the main supabase auth endpoints you are most likely to use for authentication:
+Here is a list of the main supabase auth endpoints you are most likely to use for authentication:
- `POST /auth/v1/signup`: to create a new user and get a JWT token.
- `POST /auth/v1/token`: to authenticate a user and get a JWT token. (multiple grant types are supported, check the documentation for more details)
- `POST /auth/v1/logout`: to log out the authenticated user.
- `GET /auth/v1/user`: to get the authenticated user information.
-See the [Your supabase project's API documentation](https://supabase.com/dashboard/project/_/integrations/data_api/docs?page=users-management) for all the possible endpoints.
-
-And here is the list of all the atomic crm specific endpoints:
-
-- `GET /rest/v1/companies`: to get the list of companies.
-- `POST /rest/v1/companies`: to create a new company.
-- `GET /rest/v1/companies?id=eq.{id}`: to get companies[*](#get-one-note) by id
-- `PATCH /rest/v1/companies/?id=eq.{id}`: to update a company by id
-- `DELETE /rest/v1/companies?id=eq.{id}`: to delete a company by id
-<br />
-- `GET /rest/v1/contacts_summary`: to get the list of contacts with their company name and number of tasks.
-<br />
-- `GET /rest/v1/configuration`: to get the configuration of the CRM, including the custom fields.
-<br />
-- `GET /rest/v1/contacts`: to get the list of contacts.
-- `POST /rest/v1/contacts`: to create a new contact.
-- `GET /rest/v1/contacts?id=eq.{id}`: to get contacts[*](#get-one-note) by id
-- `PATCH /rest/v1/contacts?id=eq.{id}`: to update a contact by id
-- `DELETE /rest/v1/contacts?id=eq.{id}`: to delete a contact by id.
-<br />
-- `GET /rest/v1/tasks`: to get the list of tasks.
-- `POST /rest/v1/tasks`: to create a new task.
-- `GET /rest/v1/tasks?id=eq.{id}`: to get tasks[*](#get-one-note) by id
-- `PATCH /rest/v1/tasks?id=eq.{id}`: to update a task by id
-- `DELETE /rest/v1/tasks?id=eq.{id}`: to delete a task by id
-<br />
-- `GET /rest/v1/companies_summary`: to get the list of companies with the number of contacts and tasks.
-<br />
-- `GET /rest/v1/deals`: to get the list of deals.
-- `POST /rest/v1/deals`: to create a new deal.
-- `GET /rest/v1/deals?id=eq.{id}`: to get deals[*](#get-one-note) by id
-- `PATCH /rest/v1/deals?id=eq.{id}`: to update a deal by id
-- `DELETE /rest/v1/deals?id=eq.{id}`: to delete a deal by id
-<br />
-- `GET /rest/v1/deal_notes`: to get the list of deal notes.
-- `POST /rest/v1/deal_notes`: to create a new deal note.
-- `GET /rest/v1/deal_notes?id=eq.{id}`: to get deal notes[*](#get-one-note) by id
-- `PATCH /rest/v1/deal_notes?id=eq.{id}`: to update a deal note by id
-- `DELETE /rest/v1/deal_notes?id=eq.{id}`: to delete a deal note by id
-<br />
-- `GET /rest/v1/contact_notes`: to get the list of contact notes.
-- `POST /rest/v1/contact_notes`: to create a new contact note.
-- `GET /rest/v1/contact_notes?id=eq.{id}`: to get contact notes[*](#get-one-note) by id
-- `PATCH /rest/v1/contact_notes?id=eq.{id}`: to update a contact note by id
-- `DELETE /rest/v1/contact_notes?id=eq.{id}`: to delete a contact note by id
-
-> <a id="get-one-note"></a>
-> All GET query in Postgrest will always returns a list of items by default. To have the query returns a single item directly, you can add the Accept header with the value `Accept: application/vnd.pgrst.object+json` to your request.
-
-
-Supabase use Postgrest so the route supports all the query parameters supported by Postgrest.
-To filter the list of contacts by status, you can use the following query:
+See the [Supabase project's API documentation](https://supabase.com/dashboard/project/_/integrations/data_api/docs?page=users-management) for all the possible endpoints.
+
+## Data API Endpoints
+
+Here is the list of all the atomic crm specific endpoints:
+
+- contacts
+ - `GET /rest/v1/contacts_summary`: to get the list of contacts with their company name and number of tasks.
+ - `GET /rest/v1/contacts`: to get the list of contacts.
+ - `POST /rest/v1/contacts`: to create a new contact.
+ - `GET /rest/v1/contacts?id=eq.{id}`: to get contacts[*](#get-one-note) by id
+ - `PATCH /rest/v1/contacts?id=eq.{id}`: to update a contact by id
+ - `DELETE /rest/v1/contacts?id=eq.{id}`: to delete a contact by id.
+- contact notes
+ - `GET /rest/v1/contact_notes`: to get the list of contact notes.
+ - `POST /rest/v1/contact_notes`: to create a new contact note.
+ - `GET /rest/v1/contact_notes?id=eq.{id}`: to get contact notes[*](#get-one-note) by id
+ - `PATCH /rest/v1/contact_notes?id=eq.{id}`: to update a contact note by id
+ - `DELETE /rest/v1/contact_notes?id=eq.{id}`: to delete a contact note by id
+- tasks
+ - `GET /rest/v1/tasks`: to get the list of tasks.
+ - `POST /rest/v1/tasks`: to create a new task.
+ - `GET /rest/v1/tasks?id=eq.{id}`: to get tasks[*](#get-one-note) by id
+ - `PATCH /rest/v1/tasks?id=eq.{id}`: to update a task by id
+ - `DELETE /rest/v1/tasks?id=eq.{id}`: to delete a task by id
+- companies
+ - `GET /rest/v1/companies_summary`: to get the list of companies with the number of contacts and tasks.
+ - `GET /rest/v1/companies`: to get the list of companies.
+ - `POST /rest/v1/companies`: to create a new company.
+ - `GET /rest/v1/companies?id=eq.{id}`: to get companies[*](#get-one-note) by id
+ - `PATCH /rest/v1/companies/?id=eq.{id}`: to update a company by id
+ - `DELETE /rest/v1/companies?id=eq.{id}`: to delete a company by id
+- deals
+ - `GET /rest/v1/deals`: to get the list of deals.
+ - `POST /rest/v1/deals`: to create a new deal.
+ - `GET /rest/v1/deals?id=eq.{id}`: to get deals[*](#get-one-note) by id
+ - `PATCH /rest/v1/deals?id=eq.{id}`: to update a deal by id
+ - `DELETE /rest/v1/deals?id=eq.{id}`: to delete a deal by id
+- deal notes
+ - `GET /rest/v1/deal_notes`: to get the list of deal notes.
+ - `POST /rest/v1/deal_notes`: to create a new deal note.
+ - `GET /rest/v1/deal_notes?id=eq.{id}`: to get deal notes[*](#get-one-note) by id
+ - `PATCH /rest/v1/deal_notes?id=eq.{id}`: to update a deal note by id
+ - `DELETE /rest/v1/deal_notes?id=eq.{id}`: to delete a deal note by id
+- configuration
+ - `GET /rest/v1/configuration`: to get the configuration of the CRM, including the custom fields.
+
+These API endpoints are generated from the database schema via [PostgREST](https://docs.postgrest.org/en/latest/).
+
+:::tip
+<a id="get-one-note"></a>
+All GET query in Postgrest will always returns a list of items by default. To have the query returns a single item directly, you can add the Accept header with the value `Accept: application/vnd.pgrst.object+json` to your request.
+:::
+
+API Endpoints support all the query parameters supported by Postgrest. For example, to filter the list of contacts by status, you can use the following query:
```
GET /rest/v1/contacts?status=eq.hot
@@ -131,20 +142,15 @@ To only get the last_name and first_name of the contacts, you can use the follow
GET /rest/v1/contacts?select=last_name,first_name
```
-Note: For more details on the available query parameters, and other possibilities (like calling functions) check the [Postgrest documentation](https://postgrest.org/en/stable/references/api.html).
-
-## Example: Authenticating and finding a contact by email and then adding a note to this contact
+:::note
+For more details on the available query parameters, and other possibilities (like calling functions) check the [Postgrest documentation](https://postgrest.org/en/stable/references/api.html).
+:::
-Let's say you want to integrate the CRM with another tool, like one where you have a list of contacts that send you messages, and you want to automatically add these messages as notes to the corresponding contact in the CRM.
-You can create a widget that listens to incoming messages, and for each message, it calls the API to find the contact by email, and then adds a note to this contact with the content of the message.
+## Example Usage
-First you need to retrieve the API key of your Supabase project, you can find it in the Supabase dashboard in the settings section.
+Let's say you want to integrate the CRM with another tool with a widget that allows to save a note for a contact.
-Here I'm using JavaScript and the native `fetch` API to make the HTTP requests, but you can use any programming language and any HTTP client.
-You could also use the supabase client library to do it, but here we want to show how to do it without the supabase client library, so we are making the HTTP requests directly.
-I'm also doing it in a single function for simplicity.
-In a real application, you probably would do this in multiple functions, and handle errors and edge cases (like the contact not being found) properly.
-How to intercept incoming messages and trigger this function is out of the scope of this document.
+The following example is using JavaScript and the native `fetch` API to make the HTTP requests, but you can use any programming language and any HTTP client. You could also use the `supabase` client library to do it.
```js
async function addMessageAsNoteToContact({