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

# Binated API

Jentic publishes the only available OpenAPI specification for Binated API, keeping it validated and agent-ready. The Binated API is the programmatic interface to the Binated business-intelligence and data-analytics platform, exposing 12 endpoints to register data sources, query them, and manage dashboards and reports. It supports the standard BI loop: connect a source, run queries against it, build dashboards from the results, and generate point-in-time reports. Authentication is by HTTP bearer token in JWT format.

## For AI agents

Connect data sources, run queries, and build dashboards and reports through the Binated business-intelligence platform.

## Scope

Does not handle ETL pipeline scheduling, user-permission management, or data-warehouse provisioning - use for registering data sources, querying them, and managing Binated dashboards and reports only.

## Capabilities

- Register data sources via POST /datasources and run queries against them with POST `/datasources/{sourceId}/query`
- List, retrieve, and delete configured data sources for governance
- Create dashboards on top of registered sources via POST /dashboards
- Update dashboards in place with PATCH `/dashboards/{dashboardId}`
- Generate point-in-time reports via POST /reports and retrieve them by ID
- List existing dashboards and reports for inventory and access control

## Use cases

### Programmatic Dashboard Provisioning

Analytics teams onboarding new customers want each tenant to receive a starter dashboard built from their data source. The Binated API supports this with POST /datasources to register the source and POST /dashboards to create the dashboard, plus PATCH `/dashboards/{dashboardId}` to apply tenant-specific overrides. Setup is typically two days for the provisioning script.

Example prompt: Register a Postgres source via POST /datasources, then create a dashboard via POST /dashboards bound to that source ID and confirm via GET `/dashboards/{dashboardId}.`

### Scheduled Report Generation

Operations and finance teams need point-in-time reports delivered on a schedule. The Binated API exposes POST /reports to generate and GET `/reports/{reportId}` to retrieve, which a cron-driven job can call once per period and forward to email or storage. Setup is half a day per report definition.

Example prompt: Generate a monthly revenue report via POST /reports with a fixed query against the configured source, then retrieve it via GET `/reports/{reportId}` and forward the result by email.

### Embedded Analytics Query Layer

Product teams embedding analytics in their own UI need to run user-scoped queries against the data sources they have registered with Binated. POST `/datasources/{sourceId}/query` is the supported entry point, returning query results that the embedding application then renders. This separates query execution from rendering and keeps source credentials in Binated. Setup is typically two to three days for a first embed.

Example prompt: Send a SQL-shaped query against data source ID 42 via POST `/datasources/{sourceId}/query` and return the result rows for rendering in a customer-facing chart.

### AI Agent Analyst via Jentic

An AI assistant for analytics teams can register sources, run queries, and produce reports from natural-language requests routed through Jentic. The bearer JWT is held in your Jentic One instance, so the assistant never sees the raw token. Search-load-execute through Jentic gets the assistant live in under an hour, versus several days for a direct integration.

Example prompt: Search Jentic for 'run a Binated query', load the POST `/datasources/{sourceId}/query` schema, and execute it against the configured source with the supplied query.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/datasources` | Register a new data source |
| POST | `/datasources/{sourceId}/query` | Run a query against a data source |
| GET | `/datasources` | List configured data sources |
| POST | `/dashboards` | Create a dashboard |
| PATCH | `/dashboards/{dashboardId}` | Update a dashboard |
| POST | `/reports` | Generate a report |
| GET | `/reports/{reportId}` | Retrieve a report by ID |

## Key resources

- **Data Sources** — Register, list, retrieve, delete, and query data sources connected to Binated
- **Dashboards** — Create, list, retrieve, and update dashboards built on registered data sources
- **Reports** — Generate point-in-time reports, list them, and retrieve a single report by ID

## Why Jentic

- **Setup:** Wiring the Binated API by hand means implementing its bearer-token auth, pointing at the api.binated.com/v1 host, and writing your own retry handling around data-source and dashboard calls. Through Jentic you install once, import Binated from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Binated puts the source id in the URL path (`/datasources/{sourceId}/query`), so a rule can pin your agent to one data source: it can query and read that source and nothing else. You choose the operations it may call, so dashboard edits like PATCH `/dashboards/{dashboardId}` are not included unless you add them.
- **Credential handling:** Your Binated 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 'run a Binated query' or 'create a dashboard', and Jentic returns the matching Binated operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Tableau** — Enterprise BI platform with much larger surface than Binated
- **Metabase** — Open-source BI platform with similar dashboard and query primitives
- **Bimbala** — Lightweight platform-resource API that can feed records into a Binated source

## FAQ

### Why is there no official OpenAPI spec for Binated API?

Binated does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Binated API 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 Binated API use?

The Binated API uses HTTP bearer authentication with a JWT token. You supply the token as Authorization: Bearer <jwt>. When called via Jentic, the JWT is held in your Jentic One instance so the raw token never reaches the agent's context.

### Can I run a query against a registered data source through the Binated API?

Yes. POST `/datasources/{sourceId}/query` runs a query against the named data source and returns the result. Sources are registered first via POST /datasources, then queried by their assigned source ID.

### What are the rate limits for the Binated API?

The current spec does not declare explicit numeric rate limits. Treat 429 responses as the signal to back off, and call the Jentic SDK, which retries on 429 with exponential back-off so high-volume query jobs do not have to handle this manually.

### How do I generate a Binated report through Jentic?

Search Jentic for 'generate a Binated report', which surfaces POST /reports. Load the schema, supply the report definition, and execute. Then retrieve the result via GET `/reports/{reportId}.` The Python flow is: pip install jentic, then await client.search, await client.load, await client.execute.

### Can I update an existing dashboard?

Yes. PATCH `/dashboards/{dashboardId}` applies a partial update to a dashboard, leaving fields not present in the request unchanged. This is the supported pattern for tenant-specific overrides on a shared dashboard template.

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

Yes. Because you self-host Jentic One, your own rules decide which Binated operations and credentials the agent may use. Since the source ID sits in the path (POST `/datasources/{sourceId}/query`), you can pin the agent to a single data source so it can query and read that source and nothing else. You also choose the operations it may call, so dashboard edits like PATCH `/dashboards/{dashboardId}` and report generation via POST /reports are excluded unless you add them.