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

# API Introduction

> Authenticate with an API key and make your first request

The SabaothCloud API lets you automate what you do in the dashboard from scripts, CI pipelines and other tools. Requests are authenticated with an API key.

## Base URL

```
https://api.sabaothcloud.com/api/v1
```

All requests use HTTPS. Request and response bodies are JSON.

## Authentication

1. Create an API key in the dashboard under **API Keys**. See [API keys](/dashboard/api-keys).
2. Send it in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer mpg_YOUR_API_KEY
```

API keys start with `mpg_`. A key belongs to one organization and can do only what both of these allow:

* Your role in that organization
* The scopes chosen when the key was created

## Your first request

List the PostgreSQL services in an organization. You need the `clusters:read` scope.

```bash theme={null}
curl "https://api.sabaothcloud.com/api/v1/clusters?organization_id=YOUR_ORG_ID" \
  -H "Authorization: Bearer mpg_YOUR_API_KEY"
```

<Tip>
  Your organization ID is in the dashboard URL after `/org/`, for example `https://sabaothcloud.com/dashboard/org/YOUR_ORG_ID/overview`.
</Tip>

## Errors

Errors return a non-2xx status code and a JSON body:

```json theme={null}
{
  "error": "NotFound",
  "message": "API key not found"
}
```

Some errors include a `details` object with more information.

| Status | Meaning |
| - | - |
| `400` | The request is invalid. Check `message` for the field that failed. |
| `401` | The API key is missing, invalid, expired or revoked. |
| `403` | The key's scopes or your role don't allow this action. |
| `404` | The resource doesn't exist, or you can't access it. |
| `409` | The resource is busy, for example a service is still changing. Retry after the number of seconds in the `Retry-After` header. |
| `429` | Too many requests. Wait for the number of seconds in the `Retry-After` header. |
| `5xx` | Something went wrong on our side. Retry with backoff, and contact support if it continues. |

## Rate limits

When you send too many requests, the API responds with `429` and these headers:

| Header | Description |
| - | - |
| `Retry-After` | Seconds to wait before retrying. |
| `X-RateLimit-Limit` | Requests allowed in the current window. |
| `X-RateLimit-Reset` | When the window resets. |

## Keep keys safe

* Store keys in a secrets manager or your CI provider's secret store, never in source code.
* Give each key only the scopes it needs.
* Revoke keys you no longer use, and immediately if one may have leaked.

## API key endpoints

These endpoints create and manage API keys. They take a signed-in session token, not an API key, in the `Authorization` header. For most people, the simplest way to manage keys is the [API Keys](/dashboard/api-keys) page in the dashboard.

<CardGroup cols={2}>
  <Card title="Create an API key" icon="plus" href="/api-reference/api-keys/create">
    `POST /api-keys`
  </Card>

  <Card title="List API keys" icon="list" href="/api-reference/api-keys/list">
    `GET /api-keys`
  </Card>

  <Card title="Get an API key" icon="magnifying-glass" href="/api-reference/api-keys/get">
    `GET /api-keys/{id}`
  </Card>

  <Card title="Revoke an API key" icon="ban" href="/api-reference/api-keys/revoke">
    `POST /api-keys/{id}/revoke`
  </Card>

  <Card title="Delete an API key" icon="trash" href="/api-reference/api-keys/delete">
    `DELETE /api-keys/{id}`
  </Card>
</CardGroup>


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