# 🚀 Getting Started

The Saturation API makes it easy to bring your projects and budgets into your own apps or workflows. In this guide, you’ll grab an API key, make your first request, and start building in just a few minutes.

**Base URL**


```http
https://api.saturation.io/api/v1
```

## 🔑 Step 1: Grab Your API Key

1. Log into Saturation and open your workspace
2. Head to **Settings → API Keys**
3. Click **Generate New API Key**
4. Copy it right away and store it safely (in `.env` or your secret manager)


## 🔐 Step 2: Authenticate Requests

Add your API key to the request headers:


```
X-API-Key: your-api-key-here
```

**Example (cURL):**


```bash
curl "https://api.saturation.io/api/v1/projects" \
  -H "X-API-Key: $SATURATION_API_KEY"
```

## 🛠️ Step 3: List Your Projects

**Example (JavaScript):**


```js
const API_BASE = 'https://api.saturation.io/api/v1';
const headers = {
  'X-API-Key': process.env.SATURATION_API_KEY,
  'Content-Type': 'application/json'
};

const list = await fetch(`${API_BASE}/projects`, { headers });
const data = await list.json();
console.log('Projects:', data.projects);
```

👉 `GET /projects` returns `{ projects: Project[] }`.

## 📘 Working with Budgets

Every project has its own budget. You can:

* `GET /projects/:projectId/budget` → fetch the budget
* `POST /projects/:projectId/budget` → add budget lines
* `GET /projects/:projectId/budget/accounts` → list accounts


## 🧩 Example: Add Budget Lines

**Example (JavaScript):**


```js
const API = 'https://api.saturation.io/api/v1';
const headers = {
  'X-API-Key': process.env.SATURATION_API_KEY,
  'Content-Type': 'application/json'
};

const projectId = '<your-project-id>';

await fetch(`${API}/projects/${projectId}/budget`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    lines: [
      {
        type: 'line',
        accountId: '1000',
        description: 'Paid Social Ads',
        phaseData: {
          estimate: {
            quantity: 1,
            rate: 25000
          }
        }
      },
      {
        type: 'subtotal',
        description: 'Campaign Subtotal',
        color: 'indigo'
      }
    ]
  })
});
```

## ⚠️ Common Errors

* `401 Unauthorized` → Invalid or missing API key
* `403 Forbidden` → Workspace access restricted
* `404 Not Found` → Project or resource not found
* `429 Too Many Requests` → Slow down; retry after a delay


## 💡 Best Practices

* Keep your API key safe (server-side only)
* Use a secret manager or `.env` file
* Rotate keys regularly
* Use pagination for big lists
* Prefer `idMode='user'` for human readable IDs like accounting codes
* Always handle non-200 responses


## 📩 Need Help?

We’ve got you covered. Reach out anytime: **[support@saturation.io](mailto:support@saturation.io)**

✨ That’s it! You’re ready to explore the API and start building.