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

# Overview

> Programmatic access to Basedash features

Basedash provides a public API for programmatic access to certain features. This page describes how to authenticate and interact with the API.

<Note>
  The API is currently unversioned, and breaking changes will be communicated in
  advance when possible.
</Note>

## Base URL

Most API endpoints are available at:

```
https://charts.basedash.com/api/public/
```

The SSO endpoint for embedding uses a different path:

```
https://charts.basedash.com/api/sso/jwt
```

## Authentication

The public API uses API key authentication via Bearer tokens.

### Creating an API key

To create an API key, open **Settings → API keys** and click **Create API key**.

When you create an API key, you'll be shown the full key once. Make sure to copy and store it securely, as it cannot be retrieved later.

### API key format

API keys follow the format `bd_key_<secret>`, where `<secret>` is a 32-character cryptographically secure random string.

Example: `bd_key_aBcD1234eFgH5678iJkL9012mNoP`

### Using your API key

Include your API key in the `Authorization` header using the Bearer scheme:

```
Authorization: Bearer <basedash_api_key>
```

Example with curl:

```bash theme={"dark"}
curl -X POST https://charts.basedash.com/api/public/organizations \
  -H "Authorization: Bearer <basedash_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Organization"}'
```

## Request format

* All requests with a body should use `Content-Type: application/json`.
* Request bodies should be valid JSON.

## Response format

All responses use a standardized wrapper format for consistency.

### Successful responses

Successful responses wrap the result in a `data` property:

```json theme={"dark"}
{
  "data": {
    "id": "org_abc123",
    "name": "My Organization",
    "slug": "my-organization",
    "customAiContext": null,
    "onboardingStatus": "STARTED"
  }
}
```

The HTTP status code indicates the type of success:

| Status code | Description                                 |
| ----------- | ------------------------------------------- |
| 200         | OK - Request succeeded                      |
| 201         | Created - Resource was successfully created |

### Error responses

Error responses wrap the error details in an `error` property, following a format inspired by [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807):

```json theme={"dark"}
{
  "error": {
    "title": "ErrorType",
    "detail": "A human-readable description of the error"
  }
}
```

| Field          | Type   | Description                                                                     |
| -------------- | ------ | ------------------------------------------------------------------------------- |
| `error.title`  | string | A short identifier for the error type (e.g., `ValidationError`, `Unauthorized`) |
| `error.detail` | string | A human-readable explanation of what went wrong                                 |