A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Snowflake API is how an app or AI agent works with a Snowflake account: running SQL queries and statements, managing databases, schemas, and tables, and administering warehouses, users, and roles. Access is granted through an OAuth or key-pair token, never a password, and every call runs as a single Snowflake role whose privileges decide what it can read or change. Snowflake does not push events, so long-running work is handled by submitting a statement and polling for its result.
How an app or AI agent connects to Snowflake determines what it can reach. There is a route for running SQL, a route for managing objects like databases and warehouses, and a Snowflake-managed server that exposes Snowflake tools to agents, and each one runs under a Snowflake role that decides what it can see and change.
The SQL API runs SQL statements over HTTPS at an account host under the /api/v2/statements path. A statement runs synchronously and returns its results if it finishes within about 45 seconds, otherwise it returns a handle to poll for the result.
The Snowflake REST APIs manage account objects like databases, schemas, tables, warehouses, users, and roles under the /api/v2 path, without writing SQL. Each call maps to a SQL command such as CREATE WAREHOUSE or DROP TABLE.
Snowflake's managed MCP server lets an agent call Snowflake through the Model Context Protocol, hosted inside Snowflake with no separate infrastructure. It exposes Cortex Analyst, Cortex Search, Cortex Agents, and SQL execution that can be set to read-only, and reached an account host under the /api/v2/.../mcp-servers/ path. It became generally available on 4 November 2025.
OAuth sends an access token in an Authorization Bearer header. Snowflake detects the token type from the token itself, and an integration can optionally state it with the X-Snowflake-Authorization-Token-Type header set to OAUTH.
A key-pair signs a short-lived JSON Web Token, valid for at most one hour, sent in an Authorization Bearer header. The token names the account and user and is signed with the user's private key. It can be marked with the X-Snowflake-Authorization-Token-Type header set to KEYPAIR_JWT.
Workload Identity Federation lets a workload running on a supported cloud authenticate with its own cloud identity instead of a Snowflake-managed secret, removing the need to store a key or token.
The Snowflake API is split into areas an agent can act on, like running SQL statements and managing databases, schemas, tables, warehouses, users, and roles. What a call can actually do is decided by the Snowflake role the session runs as, not by the API itself.
Submit SQL for execution, check the status of a running statement, and cancel one in progress.
List, create, fetch, alter, clone, and delete databases.
List, create, fetch, alter, and delete schemas inside a database.
List, create, fetch, alter, and delete tables inside a schema.
List, create, fetch, alter, and delete virtual warehouses, and suspend or resume the compute behind them.
List, create, fetch, alter, and delete users, and grant or revoke their roles.
List, create, and delete roles, and grant or revoke the privileges attached to them.
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 | |
|---|---|---|---|---|---|---|
SQL statementsSubmit SQL for execution, check the status of a running statement, and cancel one in progress.3 | ||||||
| POST | /api/v2/statements | Submit one or more SQL statements for execution. Runs synchronously, returning results if the statement finishes within about 45 seconds, otherwise returning a handle to poll. | write | — | Current | |
Whether this reads or writes depends entirely on the SQL submitted and the role the session runs as. The request body can name the database, schema, warehouse, and role for the statement; if omitted, the user's defaults apply. A statement can do anything that role is allowed to do. Acts onstatement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/statements/{statementHandle} | Check the status of a submitted statement and retrieve its results once execution has completed. | read | — | Current | |
Returns 200 with results when the statement has finished, or 202 while it is still running. Large result sets are split into partitions selected by the partition query parameter, with a Link header pointing to the first, next, previous, and last partitions. Acts onstatement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/statements/{statementHandle}/cancel | Cancel the execution of a statement that is still running. | write | — | Current | |
Cancels the in-progress statement identified by the handle returned when it was submitted. Acts onstatement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DatabasesList, create, fetch, alter, clone, and delete databases.6 | ||||||
| GET | /api/v2/databases | List the databases the session role can access. | read | — | Current | |
Returns only the databases the session role has access to. Access is decided by the role, not by an API scope. Acts ondatabase Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/databases | Create a database. Equivalent to CREATE DATABASE in SQL. | write | — | Current | |
Needs the CREATE DATABASE privilege on the account, held by the session role. Acts ondatabase Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/databases/{name} | Fetch a single database. | read | — | Current | |
Needs USAGE on the database, held by the session role. Acts ondatabase Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/databases/{name} | Create a new database, or alter an existing one to match the supplied definition. | write | — | Current | |
Needs CREATE DATABASE to create, or OWNERSHIP of the database to alter, held by the session role. Acts ondatabase Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/databases/{name} | Delete a database. Equivalent to DROP DATABASE in SQL. | write | — | Current | |
Needs OWNERSHIP of the database, held by the session role. Dropping a database removes every schema and table inside it. Acts ondatabase Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/databases/{name}:clone | Clone an existing database into a new one. | write | — | Current | |
Needs CREATE DATABASE on the account plus USAGE on the source database, held by the session role. Acts ondatabase Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SchemasList, create, fetch, alter, and delete schemas inside a database.5 | ||||||
| GET | /api/v2/databases/{database}/schemas | List the schemas in a database. | read | — | Current | |
Returns only the schemas the session role can access, through USAGE on the database and schema. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/databases/{database}/schemas | Create a schema in a database. Equivalent to CREATE SCHEMA in SQL. | write | — | Current | |
Needs CREATE SCHEMA on the database, held by the session role. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/databases/{database}/schemas/{name} | Fetch a single schema. | read | — | Current | |
Needs USAGE on the schema, held by the session role. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/databases/{database}/schemas/{name} | Create a new schema, or alter an existing one to match the supplied definition. | write | — | Current | |
Needs CREATE SCHEMA to create, or OWNERSHIP of the schema to alter, held by the session role. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/databases/{database}/schemas/{name} | Delete a schema. Equivalent to DROP SCHEMA in SQL. | write | — | Current | |
Needs OWNERSHIP of the schema, held by the session role. Dropping a schema removes every table inside it. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TablesList, create, fetch, alter, and delete tables inside a schema.5 | ||||||
| GET | /api/v2/databases/{database}/schemas/{schema}/tables | List the tables in a schema. | read | — | Current | |
Returns only the tables the session role can access, through USAGE on the schema. Acts ontable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/databases/{database}/schemas/{schema}/tables | Create a table in a schema. Equivalent to CREATE TABLE in SQL. | write | — | Current | |
Needs CREATE TABLE on the schema, held by the session role. Acts ontable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/databases/{database}/schemas/{schema}/tables/{name} | Fetch a single table's definition, as returned by DESCRIBE TABLE. | read | — | Current | |
Needs USAGE on the schema and access to the table, held by the session role. This returns the table's structure, not its rows; reading rows is done by running a SELECT through the SQL statements API. Acts ontable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/databases/{database}/schemas/{schema}/tables/{name} | Create a new table, or alter an existing one to match the supplied definition. | write | — | Current | |
Needs CREATE TABLE to create, or OWNERSHIP of the table to alter, held by the session role. Acts ontable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/databases/{database}/schemas/{schema}/tables/{name} | Delete a table. Equivalent to DROP TABLE in SQL. | write | — | Current | |
Needs OWNERSHIP of the table, held by the session role. Dropping a table removes its data. Acts ontable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WarehousesList, create, fetch, alter, and delete virtual warehouses, and suspend or resume the compute behind them.6 | ||||||
| GET | /api/v2/warehouses | List the virtual warehouses in the account. Equivalent to SHOW WAREHOUSES in SQL. | read | — | Current | |
Returns the warehouses the session role can see. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/warehouses | Create a virtual warehouse. Equivalent to CREATE WAREHOUSE in SQL. | write | — | Current | |
Needs the CREATE WAREHOUSE privilege on the account, held by the session role. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/warehouses/{name} | Describe a single warehouse. Equivalent to DESCRIBE WAREHOUSE in SQL. | read | — | Current | |
Needs access to the warehouse, held by the session role. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/warehouses/{name} | Remove a virtual warehouse. Equivalent to DROP WAREHOUSE in SQL. | write | — | Current | |
Needs OWNERSHIP of the warehouse, held by the session role. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/warehouses/{name}:resume | Resume a suspended warehouse, provisioning compute so it can run queries. | write | — | Current | |
Needs OPERATE on the warehouse, held by the session role. Resuming starts compute that consumes credits. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/warehouses/{name}:suspend | Suspend a warehouse, removing its compute nodes so it stops consuming credits. | write | — | Current | |
Needs OPERATE on the warehouse, held by the session role. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList, create, fetch, alter, and delete users, and grant or revoke their roles.5 | ||||||
| GET | /api/v2/users | List the users in the account. | read | — | Current | |
Listing users typically needs an administrative role such as one holding the MANAGE GRANTS or USERADMIN privilege. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/users | Create a user. Equivalent to CREATE USER in SQL. | write | — | Current | |
Needs the CREATE USER privilege on the account, usually held by USERADMIN or a higher role. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/users/{name} | Fetch a single user. | read | — | Current | |
Needs a role with the privilege to read user details, such as USERADMIN. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/users/{name} | Delete a user. Equivalent to DROP USER in SQL. | write | — | Current | |
Needs OWNERSHIP of the user, usually held by USERADMIN or a higher role. Dropping a user removes that account login. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/users/{name}/grants | Grant a role to a user. | write | — | Current | |
Needs the MANAGE GRANTS privilege, or OWNERSHIP of the role being granted, held by the session role. This widens what the target user can do. Acts onuser grant Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Roles & grantsList, create, and delete roles, and grant or revoke the privileges attached to them.6 | ||||||
| GET | /api/v2/roles | List the roles in the account. | read | — | Current | |
Returns the roles the session role can see. Acts onrole Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/roles | Create a role. Equivalent to CREATE ROLE in SQL. | write | — | Current | |
Needs the CREATE ROLE privilege on the account, usually held by SECURITYADMIN or a higher role. Acts onrole Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/roles/{name} | Delete a role. Equivalent to DROP ROLE in SQL. | write | — | Current | |
Needs OWNERSHIP of the role, usually held by SECURITYADMIN or a higher role. Dropping a role removes the privileges it carried from everyone who held it. Acts onrole Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/roles/{name}/grants | List the privileges granted to a role. | read | — | Current | |
Shows what a role can do. Needs a role able to read the target role's grants. Acts onrole grant Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/roles/{name}/grants | Grant privileges to a role. | write | — | Current | |
Needs the MANAGE GRANTS privilege, or OWNERSHIP of the object whose access is being granted, held by the session role. This widens what every user holding the role can do. Acts onrole grant Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/roles/{name}/grants:revoke | Revoke privileges from a role. | write | — | Current | |
Needs the MANAGE GRANTS privilege, or OWNERSHIP of the object, held by the session role. This narrows what every user holding the role can do. Acts onrole grant Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Snowflake does not push events to an app or AI agent. Long-running work is handled by submitting a statement and polling its status, rather than by Snowflake calling back to a receiver URL.
| Event | What it signals | Triggered by |
|---|
Snowflake does not publish a fixed request quota for the API. Under heavy server load a call can be rejected and asked to retry, and the real ceiling on throughput is the virtual warehouse a query runs on.
Snowflake does not publish a fixed per-second or per-hour request quota for the API. Under heavy server load a call can return HTTP 429, meaning the server is shedding requests and the call should be retried after a short back-off. The real ceiling on how much work the API can do is the virtual warehouse a statement runs on: the warehouse size and how many warehouses are available set how many queries can run at once and how fast they complete.
Large result sets from the SQL API are split into partitions. A response describes the partitions, and a specific partition is fetched with the partition query parameter on a GET to the statement handle. A Link header on the response points to the first, next, previous, and last partitions, which should be followed rather than constructing the URLs by hand. Object-listing endpoints accept a pattern or filter to narrow what they return.
Requests and responses are JSON. A statement that finishes within about 45 seconds returns its results inline; anything longer returns a handle to poll, and the results are then retrieved in partitions. Individual SQL limits, such as the maximum size of a statement, are set by Snowflake account parameters rather than by the API itself.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | Success | The statement finished and its results are returned. A GET on a statement handle returns 200 once execution has completed. | Read the result set from the response body, following the partition links for large results. |
| 202 | Accepted (still running) | The statement has not finished, or an asynchronous query was submitted. The response carries a statement handle and a status URL to poll. | Poll the statement with a GET on its handle until it returns 200, then read the results. |
| 422 | Unprocessable Entity | The statement failed during execution. The body holds a failure object with code, message, and sqlState explaining the SQL error. | Read the code, message, and sqlState, fix the statement, and resubmit. |
| 429 | Too Many Requests | The server is receiving too many requests under its current load and is shedding some of them. | Back off and retry the request after a short wait. |
Snowflake serves the API under a single path version, v2, and ships dated changes through its weekly and monthly release notes rather than minting a new version string for each one.
Snowflake serves both the SQL API and the object-management REST APIs under the v2 path. The SQL API submits statements and polls a handle for results, and the REST APIs manage databases, schemas, tables, warehouses, users, and roles. There is no dated version string to pin: behavior changes ship through Snowflake's weekly and monthly release notes, listed below as dated milestones.
The Snowflake-managed MCP server, a first-party implementation of the Model Context Protocol hosted inside Snowflake, became generally available. It exposes Cortex Analyst, Cortex Search, Cortex Agents, and SQL execution that can be set to read-only, authenticates with OAuth, and is governed by role-based access control, running under the connecting user's default role. It is not supported in government regions.
Snowflake announced the general availability of the Snowflake REST APIs, the endpoints that manage account resources like databases, schemas, tables, warehouses, users, and roles under the v2 path without writing SQL. The APIs are not supported in government regions. It was announced in the 8.40 release of 21 to 23 October 2024.
An integration calls the v2 path and tracks behavior changes through the release notes.
Snowflake release notes ↗Bollard AI sits between a team's AI agents and Snowflake. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.