canonical: https://jentic.com/apis/chartbrew.com/chartbrew

# Chartbrew API reference

Jentic publishes the only available OpenAPI specification for Chartbrew API reference, keeping it validated and agent-ready. Chartbrew is an open-source business intelligence platform for connecting data sources, building charts, and assembling shareable dashboards. The API exposes teams, connections, datasets, data requests, projects, and charts so that an agent can wire up a SQL or REST data source, define a query, render a chart, and embed it on a public dashboard. It uses bearer-token authentication and 51 endpoints organised around team-scoped resources.

## For AI agents

Connect data sources, build charts, and publish shareable BI dashboards in Chartbrew. Bearer-authenticated REST API with 51 endpoints across teams, connections, datasets, projects, and charts.

## Scope

Does not handle raw event collection, ETL pipelines, or warehouse storage - use for connecting existing data sources and building shareable BI charts only.

## Capabilities

- Connect SQL, REST, and file-based data sources to a Chartbrew team via /team/{team_id}/connections
- Define datasets and data requests that fetch the underlying data for each chart
- Create projects (dashboards) and add charts that visualise dataset query results
- Generate share tokens and share-policy entries to expose a project as a public dashboard
- Manage variable bindings on data requests so the same query can be parameterised across charts
- Run a single data request on demand to refresh a chart without rebuilding the dataset
- Retrieve charts by share string for embedding into external pages without requiring login

## Use cases

### Embed a self-serve BI dashboard in a customer portal

Spin up a Chartbrew project, attach a database connection, define datasets, and add charts so a SaaS team can embed customer-facing analytics in their own product. The share-policy endpoints let you scope access per project and the share-token flow returns a string that resolves to a read-only dashboard URL. End-to-end setup with the API takes a few hours rather than days of front-end work.

Example prompt: Create a project named 'Customer Usage', attach an existing Postgres connection, add three line charts driven by a daily-active-users dataset, and return a share token that resolves to a public dashboard URL

### Programmatically refresh data behind a chart

When an upstream pipeline finishes, an agent can call the run-data-request endpoint to pull fresh values into a single chart without rebuilding the entire dataset. This keeps Chartbrew charts in sync with batch ETL jobs while avoiding full dataset re-imports for every chart on a dashboard.

Example prompt: After an Airflow DAG completes, call POST /team/{team_id}/datasets/{dataset_id}/dataRequests/{id}/request for each chart on the executive dashboard and confirm the refresh succeeded

### Parameterise a chart with runtime variables

Use variable bindings on a data request so the same SQL or REST query can be reused across multiple charts and time ranges. The variable-binding endpoints let an agent register parameters at request time, rather than hard-coding values into the dataset definition. This is useful for date ranges, customer IDs, and tenant keys.

Example prompt: Create a variable binding named 'tenant_id' on data request 42 with value 'acme', then run that data request and confirm the chart returns acme-only rows

### Provision a Chartbrew workspace from scratch via an AI agent

An AI agent discovers Chartbrew through Jentic, loads the create-team and create-connection schemas, and walks through the team-connection-dataset-chart-project chain to bootstrap a working dashboard for a new internal team. Because every step is exposed as a discrete REST call with a known input schema, the agent can recover from validation failures and retry without human intervention.

Example prompt: Search Jentic for 'create a chartbrew dashboard', load the relevant operation schemas, and create a team, connection, dataset, project, and three charts in order, returning the project share URL

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /team | Create a Chartbrew team |
| POST | /team/{team_id}/connections | Add a data source connection to a team |
| POST | /team/{team_id}/datasets | Create a dataset for use in charts |
| POST | /team/{team_id}/datasets/{dataset_id}/dataRequests/{id}/request | Run a single data request to refresh chart data |
| POST | /project | Create a project (dashboard) |
| POST | /project/{project_id}/chart | Add a chart to a project |
| POST | /project/{id}/share/token | Generate a share token for a public dashboard |
| GET | /chart/share/{share_string} | Retrieve a shared chart by its share string |

## Key resources

- **Teams** — Create teams, list members, and group all other Chartbrew resources under a team scope
- **Connections** — Register database, REST, and file-based data sources for a team and run connectivity tests
- **Datasets** — Define dataset queries on top of connections and run or refresh data requests
- **Projects** — Create dashboards (projects) and manage their share policies and tokens
- **Charts** — Add charts to a project, configure their dataset bindings, and retrieve them via share strings

## Why Jentic

- **Setup:** Wiring Chartbrew by hand means learning its bearer token auth and attaching the token to every team, dataset, and chart call yourself. Through Jentic you install once, import Chartbrew from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Chartbrew puts the team and project ids in the URL path (/team/{team_id}/..., /project/{project_id}/...), so a rule can pin your agent to one team or project: it can add connections, datasets, and charts there and nothing else. You choose the operations it may call, so creating new teams is not included unless you add it.
- **Credential handling:** Your Chartbrew bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a chartbrew dashboard' or 'add a chart to a project', and Jentic returns the matching Chartbrew operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ChartHop API** — ChartHop is a people-analytics platform - pair it with Chartbrew to visualise HR data on a self-hosted dashboard.
- **ChartMogul API** — ChartMogul is a hosted subscription-analytics product - choose it over Chartbrew when you want SaaS metrics out of the box rather than building from SQL.
- **ChartMogul API** — Second ChartMogul surface focused on the full subscription-analytics dataset.

## FAQ

### Why is there no official OpenAPI spec for Chartbrew API reference?

Chartbrew does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Chartbrew API reference via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Chartbrew API reference use?

The Chartbrew API uses HTTP bearer-token authentication. Every request must include an Authorization header of the form 'Bearer <token>'. Through Jentic, the bearer token is stored in your encrypted Jentic One instance and never exposed to the agent's prompt context.

### Can I create a public shareable dashboard with the Chartbrew API?

Yes. Create a project, then call POST /project/{id}/share/token to generate a share token. You can also configure granular access through POST /project/{id}/share/policy. The returned token resolves to a public dashboard URL that can be embedded in another site.

### How do I refresh just one chart without rebuilding the whole dataset?

Call POST /team/{team_id}/datasets/{dataset_id}/dataRequests/{id}/request. This runs a single data request bound to one chart, which is the right approach when an upstream ETL job finishes and only some charts need fresh data.

### How do I build a Chartbrew dashboard through Jentic?

Run pip install jentic, set JENTIC_AGENT_API_KEY, then search 'create a chartbrew dashboard'. Jentic returns the create-team, create-connection, create-dataset, create-project, and create-chart operations with their input schemas so the agent can chain the calls without browsing docs.

### Are there documented rate limits for the Chartbrew API?

The OpenAPI specification does not declare rate-limit headers or quotas, and Chartbrew is typically self-hosted, so limits are governed by the deployment's own infrastructure rather than a vendor-imposed quota. Check the headers on a 429 response from your specific instance to learn its limits.

### Can I limit what my agent is allowed to do with the Chartbrew API?

Yes. Because you run Jentic One yourself, your own rules decide which Chartbrew operations and credentials the agent can use, and Chartbrew puts the team and project ids directly in the URL path (/team/{team_id}/... and /project/{project_id}/...), so a rule can pin the agent to one team or project. You choose exactly which calls it may make, such as adding connections, datasets, and charts to that scope while leaving everything else off. Creating new teams is not included unless you explicitly grant it, and the bearer token stays with your instance rather than the agent's context.