A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Databricks API is how an app or AI agent works with a Databricks workspace: running jobs and clusters, executing SQL on a warehouse, and reading the catalogs, schemas, and tables in its data hierarchy. Access is granted through a bearer token, either an OAuth token or a personal access token, and what that token can reach is set by workspace permissions on objects like jobs and by Unity Catalog privileges on the data, rather than per-endpoint scopes. Databricks also ships managed servers that expose its tools to agents, with the same permissions always enforced.
How an app or AI agent connects to Databricks determines what it can reach. There is a route for calling the workspace REST API, and a set of hosted servers that expose Databricks tools to agents, each governed by the token behind it and the workspace and Unity Catalog permissions that token carries.
The workspace REST API answers at the per-workspace host, like https://
Databricks ships managed Model Context Protocol servers, in Public Preview, that expose workspace tools to AI agents at the per-workspace host. The paths are /api/2.0/mcp/functions/{catalog}/{schema} for Unity Catalog functions, /api/2.0/mcp/vector-search/{catalog}/{schema} for vector search indexes, /api/2.0/mcp/genie/{space_id} for a Genie space, and /api/2.0/mcp/sql for SQL. Unity Catalog permissions are always enforced, and on-behalf-of-user auth uses OAuth scopes, one per server.
A dedicated REST surface at /api/2.0/sql/statements runs SQL on a SQL warehouse without a database driver. A statement can run synchronously up to a wait timeout or asynchronously with a statement id to poll, and results come back inline or as external links. What the statement can read or change is gated by the running identity's Unity Catalog grants.
A service principal authenticates with its client ID and an OAuth secret using the client-credentials grant, with scope all-apis, and receives a one-hour access token sent as a bearer token. This is the recommended way for unattended automation and agents to connect, because the identity is a non-human service principal rather than a person.
A user signs in through the OAuth authorization-code flow and the app receives a short-lived access token plus a refresh token, acting with that user's identity and permissions. It suits interactive tools and apps that act on behalf of a signed-in person.
A personal access token is a long-lived bearer string tied to a user or service principal, sent in the Authorization header. It is simple to use but does not expire on its own, so Databricks recommends OAuth over personal access tokens for new integrations, and workspace admins can disable token creation.
The Databricks API is split into areas an agent can act on, like jobs, clusters, SQL warehouses, queries, the Unity Catalog data hierarchy, files, notebooks, and secrets. Each area has its own methods, and writes in some areas run compute, move data, or change who can reach what.
Create, read, list, update, reset, and delete jobs, trigger a run with run-now, and read or cancel job runs.
Create, list, start, and terminate all-purpose compute clusters.
Create, list, start, and stop SQL warehouses, the compute behind SQL queries.
Run a SQL statement on a warehouse, poll for its result, and cancel a running statement.
List and read catalogs, schemas, and tables, the three-level data hierarchy, and read or change the grants on them.
Upload, download, and delete files in Unity Catalog volumes, and read or write files in the older DBFS store.
Import and export notebooks and list the workspace folder tree.
List secret scopes and the keys in a scope, and write a secret value.
List, read, and create the non-human identities that agents and automation run as.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
JobsCreate, read, list, update, reset, and delete jobs, trigger a run with run-now, and read or cancel job runs.10 | ||||||
| POST | /api/2.1/jobs/create | Create a new job from a definition of tasks and a schedule. | write | CAN_MANAGE | Current | |
Needs workspace access to create jobs; the caller becomes the job owner. Any Unity Catalog data the job touches is still gated by the running identity's grants. Acts onjob Permission (capability) CAN_MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limit20 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| GET | /api/2.1/jobs/get | Get a single job's settings and metadata by job ID. | read | CAN_VIEW | Current | |
Read-only. Needs at least CAN_VIEW on the job. Acts onjob Permission (capability) CAN_VIEWVersionAvailable since the API’s base version Webhook eventNone Rate limit20 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| GET | /api/2.1/jobs/list | List jobs in the workspace, paginated. | read | CAN_VIEW | Current | |
Read-only. Returns the jobs the caller can see. Acts onjob Permission (capability) CAN_VIEWVersionAvailable since the API’s base version Webhook eventNone Rate limit20 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| POST | /api/2.1/jobs/update | Partially update a job's settings, leaving unspecified fields unchanged. | write | CAN_MANAGE | Current | |
Needs CAN_MANAGE on the job. Use reset to replace all settings instead. Acts onjob Permission (capability) CAN_MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| POST | /api/2.1/jobs/reset | Overwrite all settings for a job with a new definition. | write | CAN_MANAGE | Current | |
Needs CAN_MANAGE on the job. Unlike update, this replaces every field. Acts onjob Permission (capability) CAN_MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limit20 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| POST | /api/2.1/jobs/delete | Delete a job. | write | CAN_MANAGE | Current | |
Needs CAN_MANAGE on the job. Removes the job definition and its run history. Acts onjob Permission (capability) CAN_MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| POST | /api/2.1/jobs/run-now | Trigger a one-off run of an existing job, optionally passing parameters. | write | CAN_MANAGE_RUN | Current | |
Needs CAN_MANAGE_RUN on the job. The run executes real code and spends compute. The job runs as its configured identity, whose Unity Catalog grants gate the data it reaches. Acts onjob run Permission (capability) CAN_MANAGE_RUNVersionAvailable since the API’s base version Webhook eventNone Rate limit20 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| GET | /api/2.1/jobs/runs/list | List runs for a job or the whole workspace, paginated. | read | CAN_VIEW | Current | |
Read-only. Acts onjob run Permission (capability) CAN_VIEWVersionAvailable since the API’s base version Webhook eventNone Rate limit30 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| GET | /api/2.1/jobs/runs/get | Get the metadata, state, and tasks of a single job run. | read | CAN_VIEW | Current | |
Read-only. Acts onjob run Permission (capability) CAN_VIEWVersionAvailable since the API’s base version Webhook eventNone Rate limit100 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| POST | /api/2.1/jobs/runs/cancel | Cancel an active job run. | write | CAN_MANAGE_RUN | Current | |
Needs CAN_MANAGE_RUN on the job. Stops the run, which may leave partial work. Acts onjob run Permission (capability) CAN_MANAGE_RUNVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second per workspace SourceOfficial documentation ↗ | ||||||
ClustersCreate, list, start, and terminate all-purpose compute clusters.4 | ||||||
| POST | /api/2.0/clusters/create | Create an all-purpose compute cluster. | write | CAN_MANAGE | Current | |
Needs the Allow unrestricted cluster creation entitlement or a cluster policy. A running cluster spends compute. Acts oncluster Permission (capability) CAN_MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/clusters/list | List all-purpose clusters in the workspace. | read | CAN_VIEW | Current | |
Read-only. Acts oncluster Permission (capability) CAN_VIEWVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/clusters/start | Start a terminated cluster by ID. | write | CAN_RESTART | Current | |
Needs at least CAN_RESTART on the cluster. The cluster spends compute once running. Acts oncluster Permission (capability) CAN_RESTARTVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/clusters/delete | Terminate a cluster. The cluster definition is retained and can be started again. | write | CAN_RESTART | Current | |
Despite the name, this terminates rather than permanently removes; use permanent-delete to remove the definition. Needs at least CAN_RESTART. Acts oncluster Permission (capability) CAN_RESTARTVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SQL WarehousesCreate, list, start, and stop SQL warehouses, the compute behind SQL queries.4 | ||||||
| POST | /api/2.0/sql/warehouses | Create a SQL warehouse, the compute that runs SQL queries. | write | CAN_MANAGE | Current | |
Needs workspace access and the cluster-creation entitlement. A running warehouse spends compute. Acts onwarehouse Permission (capability) CAN_MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/sql/warehouses | List SQL warehouses the caller can access. | read | CAN_VIEW | Current | |
Read-only. Acts onwarehouse Permission (capability) CAN_VIEWVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/sql/warehouses/{id}/start | Start a stopped SQL warehouse. | write | CAN_USE | Current | |
Needs at least CAN_USE on the warehouse. It spends compute once running. Acts onwarehouse Permission (capability) CAN_USEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/sql/warehouses/{id}/stop | Stop a running SQL warehouse. | write | CAN_USE | Current | |
Needs at least CAN_USE on the warehouse. Acts onwarehouse Permission (capability) CAN_USEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SQL Statement ExecutionRun a SQL statement on a warehouse, poll for its result, and cancel a running statement.3 | ||||||
| POST | /api/2.0/sql/statements | Submit a SQL statement to run on a warehouse, with a chosen catalog, schema, and result format. | write | CAN_USE | Current | |
Marked write because a statement can be a write (INSERT, UPDATE, DELETE, CREATE). Needs CAN_USE on the warehouse, and the running identity's Unity Catalog grants decide which tables it can read or change. A wait_timeout of 0 to 50 seconds controls how long the call waits before returning a statement id to poll. Acts onstatement Permission (capability) CAN_USEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/sql/statements/{statement_id} | Get the status and result of a submitted statement by polling its ID. | read | CAN_USE | Current | |
Read-only. Used to fetch results when the execute call returned before the statement finished. Acts onstatement Permission (capability) CAN_USEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/sql/statements/{statement_id}/cancel | Cancel a running statement execution. | write | CAN_USE | Current | |
Stops execution; a partially applied write is not rolled back automatically. Acts onstatement Permission (capability) CAN_USEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Unity CatalogList and read catalogs, schemas, and tables, the three-level data hierarchy, and read or change the grants on them.5 | ||||||
| GET | /api/2.1/unity-catalog/catalogs | List catalogs, the top level of the data hierarchy, that the caller can see. | read | USE CATALOG | Current | |
Read-only. Returns catalogs the identity can use or browse. Acts oncatalog Permission (capability) USE CATALOGVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2.1/unity-catalog/schemas | List schemas within a catalog. | read | USE SCHEMA | Current | |
Read-only. Needs USE CATALOG on the parent catalog and USE SCHEMA on the schema. Acts onschema Permission (capability) USE SCHEMAVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2.1/unity-catalog/tables | List tables within a schema. | read | SELECT | Current | |
Read-only. Listing needs USE CATALOG and USE SCHEMA; reading the table's data needs SELECT on the table. Acts ontable Permission (capability) SELECTVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2.1/unity-catalog/permissions/{securable_type}/{full_name} | Read the grants on a securable object, like a catalog, schema, or table. | read | MANAGE | Current | |
Read-only. Shows who has which privilege on the object. Requires ownership or MANAGE to see the full grant set. Acts ongrant Permission (capability) MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/2.1/unity-catalog/permissions/{securable_type}/{full_name} | Grant or revoke privileges on a securable object. | write | MANAGE | Current | |
Changes who can reach the data. Requires ownership of the object or the MANAGE privilege on it. Acts ongrant Permission (capability) MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Files & DBFSUpload, download, and delete files in Unity Catalog volumes, and read or write files in the older DBFS store.5 | ||||||
| PUT | /api/2.0/fs/files{file_path} | Upload a file to a Unity Catalog volume path. | write | WRITE VOLUME | Current | |
Needs WRITE VOLUME on the volume, plus USE CATALOG and USE SCHEMA on its parents. Paths look like /Volumes/{catalog}/{schema}/{volume}/{path}. Acts onfile Permission (capability) WRITE VOLUMEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/fs/files{file_path} | Download a file from a Unity Catalog volume path. | read | READ VOLUME | Current | |
Needs READ VOLUME on the volume, plus USE CATALOG and USE SCHEMA on its parents. Acts onfile Permission (capability) READ VOLUMEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/2.0/fs/files{file_path} | Delete a file from a Unity Catalog volume path. | write | WRITE VOLUME | Current | |
Needs WRITE VOLUME on the volume. Acts onfile Permission (capability) WRITE VOLUMEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/dbfs/put | Write a file to the older Databricks File System (DBFS) store. | write | — | Current | |
DBFS predates Unity Catalog and is not governed by its grants; access is at the workspace level. Databricks recommends volumes over DBFS for new work. Limited to 30 requests per second per workspace across the /dbfs surface. Acts ondbfs file Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 requests per second per workspace (whole /dbfs surface) SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/dbfs/read | Read the contents of a file in DBFS. | read | — | Current | |
Read-only. Shares the 30 requests per second per workspace limit on the /dbfs surface. Acts ondbfs file Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 requests per second per workspace (whole /dbfs surface) SourceOfficial documentation ↗ | ||||||
Workspace (notebooks)Import and export notebooks and list the workspace folder tree.3 | ||||||
| POST | /api/2.0/workspace/import | Import a notebook or file into the workspace folder tree. | write | CAN_MANAGE | Current | |
With overwrite set, replaces existing notebook source. Needs CAN_MANAGE on the target folder. Limited to 30 requests per second per workspace. Acts onnotebook Permission (capability) CAN_MANAGEVersionAvailable since the API’s base version Webhook eventNone Rate limit30 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/workspace/export | Export a notebook or file from the workspace, in a chosen format. | read | CAN_READ | Current | |
Read-only. Needs at least CAN_READ on the object. Limited to 60 requests per second per workspace. Acts onnotebook Permission (capability) CAN_READVersionAvailable since the API’s base version Webhook eventNone Rate limit60 requests per second per workspace SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/workspace/list | List the contents of a workspace folder. | read | CAN_READ | Current | |
Read-only. Limited to 50 requests per second per workspace. Acts onnotebook Permission (capability) CAN_READVersionAvailable since the API’s base version Webhook eventNone Rate limit50 requests per second per workspace SourceOfficial documentation ↗ | ||||||
SecretsList secret scopes and the keys in a scope, and write a secret value.3 | ||||||
| GET | /api/2.0/secrets/scopes/list | List the secret scopes available in the workspace. | read | — | Current | |
Read-only metadata. Lists scope names, not secret values. Acts onsecret scope Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit1,100 requests per minute per workspace (whole Secrets surface) SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/secrets/list | List the secret keys stored in a scope. | read | READ | Current | |
Needs READ on the scope ACL. Returns key names and metadata only; secret values cannot be read back through this API. Acts onsecret Permission (capability) READVersionAvailable since the API’s base version Webhook eventNone Rate limit1,100 requests per minute per workspace (whole Secrets surface) SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/secrets/put | Create or update a secret value in a scope. | write | WRITE | Current | |
Needs WRITE (or MANAGE) on the scope ACL. Stores a credential that workloads with READ can use at run time. Acts onsecret Permission (capability) WRITEVersionAvailable since the API’s base version Webhook eventNone Rate limit1,100 requests per minute per workspace (whole Secrets surface) SourceOfficial documentation ↗ | ||||||
Service principalsList, read, and create the non-human identities that agents and automation run as.3 | ||||||
| GET | /api/2.0/preview/scim/v2/ServicePrincipals | List the service principals in the workspace. | read | — | Current | |
Read-only. The workspace SCIM surface is limited to 255 GET requests per minute per workspace. Acts onservice principal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit255 GET requests per minute per workspace (workspace SCIM surface) SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/preview/scim/v2/ServicePrincipals/{id} | Get a single service principal by ID. | read | — | Current | |
Read-only. Acts onservice principal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit255 GET requests per minute per workspace (workspace SCIM surface) SourceOfficial documentation ↗ | ||||||
| POST | /api/2.0/preview/scim/v2/ServicePrincipals | Create a service principal, a non-human identity for automation. | write | — | Current | |
Restricted to workspace admins. The new identity can then be granted workspace and Unity Catalog access. Limited to 35 write requests per minute per workspace on the SCIM surface. Acts onservice principal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit35 POST/PUT/DELETE requests per minute per workspace (workspace SCIM surface) SourceOfficial documentation ↗ | ||||||
Databricks does not publish a single general-purpose webhook product across the platform. Events are surfaced in narrower ways instead, like job run notifications and the MLflow model registry webhooks, each tied to its own feature rather than a shared event stream.
| Event | What it signals | Triggered by |
|---|
Databricks limits how fast an app or AI agent can call, through per-endpoint request rates measured per second and set per workspace. Going over returns a 429 response.
Databricks rate-limits by endpoint, set per workspace and measured per second or per minute, rather than by one account-wide quota. The Jobs API gives /jobs/run-now and /jobs/create 20 requests per second, /jobs/runs/get 100 per second, /jobs/runs/list 30 per second, and /jobs/update and /jobs/runs/cancel 10 per second. The DBFS surface is held to 30 requests per second across /dbfs, the Secrets surface to 1,100 requests per minute, and the workspace SCIM surface to 255 GET requests per minute. Each endpoint's documented limit is shown on its row where Databricks publishes one. Going over returns HTTP 429 with the error_code REQUEST_LIMIT_EXCEEDED, and the caller should back off and retry.
List endpoints page with a token model: a request returns a page of results plus a next_page_token, which is passed as page_token on the next call until no token comes back. Page size is set with max_results or page_size, which caps per endpoint, for example 25 for jobs/list and 100 for the SCIM service-principals surface. The older DBFS and some 2.0 endpoints instead page by offset and limit.
A SQL statement returns results inline when small, and switches to external links (presigned URLs) for large result sets, so a single response stays bounded; an inline chunk is capped at 25 MiB. File uploads through the UI are capped at 5 GB, while the Files API and the SDK handle larger files. A workspace file is capped at 500 MB, and a notebook at 10,000 cells.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | BAD_REQUEST / INVALID_PARAMETER_VALUE | The request is malformed or a parameter value is invalid, such as a missing required field or a value out of range. The body holds an error_code and a human-readable message. | Read the message, correct the named parameter, and resend. The request is not retryable as-is. |
| 401 | UNAUTHENTICATED | The request has no valid authentication credentials, such as a missing, malformed, or expired token. OAuth machine-to-machine tokens last only one hour. | Send a valid bearer token, and refresh an expired OAuth token before retrying. |
| 403 | PERMISSION_DENIED | The caller is authenticated but lacks permission for the operation, such as a missing object ACL like CAN_MANAGE on a job, or a missing Unity Catalog privilege like SELECT on a table. | Grant the missing workspace ACL or Unity Catalog privilege to the calling identity, then retry. |
| 404 | RESOURCE_DOES_NOT_EXIST | The operation targets a resource that does not exist, or that the token cannot see. | Confirm the ID or path, and that the identity has access in the right workspace. |
| 429 | REQUEST_LIMIT_EXCEEDED | A per-endpoint or per-workspace rate limit was exceeded. Limits are measured per second or per minute per workspace and differ by endpoint. | Back off and retry with exponential backoff and jitter, and smooth the request rate. |
| 500 | INTERNAL_ERROR | An error on the Databricks side, which can also appear as 503 or 504. | Retry with backoff for an idempotent call, and contact Databricks support if it persists. |
Databricks versions each API surface by a number in the path, so the Jobs API is at 2.1 while clusters, SQL, files, and secrets stay at 2.0. The platform itself ships dated release notes rather than a single dated API version.
The Jobs API is at version 2.1 in its path, while most other workspace surfaces (clusters, SQL warehouses, SQL Statement Execution, files, workspace, secrets) are at 2.0. Databricks versions each API surface independently by a number in the path rather than minting one account-wide dated version. Version 2.1 added multi-task jobs and a richer run model over 2.0; new integrations should target 2.1 for jobs.
Version 2.0 is the current version for most workspace surfaces: clusters, SQL warehouses, SQL Statement Execution, the Files and DBFS stores, the workspace notebook tree, and secrets. The Jobs API also had a 2.0, now superseded by 2.1 for new work. Behavioral changes across the platform ship through dated release notes rather than a new path version.
An integration pins the path version per surface and moves up when a new one ships.
Databricks platform release notes ↗Bollard AI sits between a team's AI agents and Databricks. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.