Skip to content
Last updated

🚀 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

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):

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

🛠️ Step 3: List Your Projects

Example (JavaScript):

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):

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

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

 
Next page