# Overview

# API Overview

Dripcel exposes a set of **REST API endpoints** that allow you to interact with the platform programmatically.

* **Base URL:** `https://api.dripcel.com`
* Most concepts in Dripcel (contacts, campaigns, reports, etc.) have corresponding API endpoints.
* Refer to each endpoint’s documentation for full details.

> 
:::tip
> **Tip:** Use the **Dripcel API Request Collection** with your REST client of choice for faster testing and development.
>
> :::


---

## Authentication

All API endpoints require authentication using an **API key**.

* Generate a key in your account under **Profile > API Keys**.
* Keys act like passwords — keep them safe and never expose them publicly.

**Authentication Header Example:**

```yaml
{ "Authorization": "Bearer <key>" }
```


---

## Permissions

API keys have **roles and permissions**, just like organisation members:

* Permissions are set when generating the key.
* You can modify them later via **Profile > API Keys > Modify Permissions**.
* 
:::info
  By default, API keys inherit the permissions of the user who created them (often more than necessary).

  :::


:::warning
⚠️ **Best Practice:** Always create keys with the **minimum permissions** needed.

:::

**Nested Permissions Example:**

* `contact.update.tag_ids` is nested under `contact.update`.
* If you have `contact.update`, you also have `contact.update.tag_ids`.
* But if you only have `contact.update.tag_ids`, you don’t automatically have `contact.update`.


---

## Response Format

All responses are returned in **JSON**. Each response includes an `ok` field indicating success.

**Successful Response:**

```javascript
{   "ok": true,   "data": ... } 
```

**Error Response:**

```javascript
{   "ok": false,   "error": ... } 
```

**Usage Example:**

```javascript
const response = await fetch("https://api.dripcel.com/balance", {
  headers: {
    Authorization: "Bearer <key>",
  },
});

const body = await response.json();

if (body.ok) {
  console.log("Your credit balance is", body.data);
} else {
  console.error("Error:", body.error);
}
```


---

## Rate Limiting

The API is limited to **\~50 requests per minute per organisation**.

If you exceed this, you’ll receive a `429 Too Many Requests` response.

**Rate Limit Error Example:**

```javascript
type RateLimitError = {
  ok: false;
  error: {
    resetsAt: number; // Unix timestamp
    remaining: number; // Number of requests remaining in the current window
  };
};
```


---

## Working with `_id`

Many endpoints require an `_id` (the unique identifier of a resource).

You can find IDs in two ways:


1. **In the Dripcel App** – Navigate to the resource, hover over the ID icon, and click to copy.
2. **Via GET requests** – Retrieve a list of resources, then copy the `_id` from the response.