Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs - agent API (#69647)

Jeff Bruemmer6cc10beb56b8
diff --git a/docs/ai/agent-api.md b/docs/ai/agent-api.md
new file mode 100644
index 00000000000..9fe5d85e699
--- /dev/null
+++ b/docs/ai/agent-api.md
@@ -0,0 +1,74 @@
+---
+title: Agent API
+summary: The Agent API is a REST API for building headless, agentic BI applications on top of Metabase's semantic layer, scoped to an authenticated user's permissions.
+
+---
+
+# Agent API
+
+{% include plans-blockquote.html feature="Metabase agent API" %}
+
+The Agent API is a REST API for building headless, agentic BI applications on top of Metabase's semantic layer, scoped to an authenticated user's permissions.
+
+## Why use the Agent API
+
+There are a few advantages to using the agent API over the Metabase API.
+
+- Agent endpoints are explicitly supported for building agentic BI applications.
+- The agent API is versioned, so your apps can rely on consistent responses.
+- Supports JWT auth so requests can be scoped to a user's permissions.
+- Doesn't require you to work with MBQL, which is Metabase's querying language.
+
+## Supported features
+
+The Agent API supports:
+
+- Discovering tables and metrics
+- Inspecting their fields
+- Constructing and executing queries
+
+Base path:[/api/agent](../api.html#tag/apiagent)
+
+## Authentication
+
+The Agent API supports two authentication modes, both requiring JWT to be configured in Metabase admin settings (**Admin** > **Settings** > **Authentication** > **JWT**):
+
+### 1. Stateless JWT (recommended for agents)
+
+Pass a signed JWT directly in each request:
+
+```
+Authorization: Bearer <jwt>
+```
+
+The JWT must be signed with the shared secret configured in Metabase. Claims include:
+
+| Claim | Type | Required | Description |
+| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| iat | int | Yes | Issued-at time (Unix seconds). JWT must be <180 seconds old. |
+| email | string | Yes | Email matching a Metabase user. The claim name is configurable via the jwt-attribute-email admin setting (default: "email"). |
+| first_name | string | No | User's first name. |
+| last_name | string | No | User's last name. |
+| groups | array | No | List of groups for group sync. |
+
+Example JWT payload:
+
+```json
+{
+ "iat": 1706640000,
+ "email": "[email protected]"
+}
+```
+
+### 2. Session-based
+
+Exchange a JWT at `POST /auth/sso` to get a session token, then pass the session token via:
+
+```
+X-Metabase-Session: <session-token>
+```
+
+## Further reading
+
+- [Metabase API docs](../api.html)
+- [JWT authentication](../people-and-groups/authenticating-with-jwt.md)
diff --git a/docs/ai/start.md b/docs/ai/start.md
index 88572aca73b..d889ed5262b 100644
--- a/docs/ai/start.md
+++ b/docs/ai/start.md
@@ -13,3 +13,7 @@ Metabot is an AI assistant that helps you explore and analyze your data.
## [Setting up Metabot](./settings.md)
Admins can configure Metabot to focus on specific collections and manage example prompts.
+
+## [Agent API](./agent-api.md)
+
+A REST API for building headless, agentic BI applications on top of Metabase's semantic layer.