snowflake-api

Snowflake's SQL API v2 (/api/v2/statements) is a thin REST layer for running SQL and fetching results. POST a SQL string, get back a statement handle and either the result (for fast queries) or a 202 Accepted to poll. Large results are split into partitions you fetch one at a time. There is no separate "list tables" endpoint — catalog browsing is just SQL (SHOW TABLES, INFORMATION_SCHEMA).

Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys. Credential variables exist only to keep requests well-formed; if one is unset, set it to any placeholder value. A persistent 401 means the credential isn't configured for this workspace — report that instead of debugging auth.

The account identifier must be real — it's the hostname. It's the part of the Snowflake URL before .snowflakecomputing.com — e.g. xy12345.us-east-1 or an org-style myorg-myaccount.

export SNOWFLAKE_ACCOUNT="xy12345.us-east-1"           # your account identifier — must be real
export SNOWFLAKE_BASE="https://${SNOWFLAKE_ACCOUNT}.snowflakecomputing.com"
export SNOWFLAKE_TOKEN="placeholder"                   # injected by the runtime; any value works
export SNOWFLAKE_TOKEN_TYPE="${SNOWFLAKE_TOKEN_TYPE:-OAUTH}"   # leave as provided by the runtime

Helper and sanity check

Every request carries the same headers. Define a helper once:

snowapi() {
  curl -sS --compressed "$@" \
    -H "Authorization: Bearer ${SNOWFLAKE_TOKEN}" \
    -H "X-Snowflake-Authorization-Token-Type: ${SNOWFLAKE_TOKEN_TYPE}" \
    -H "Content-Type: application/json" -H "Accept: application/json" \
    -H "User-Agent: curl-sql-api/1.0"
}

(User-Agent is required — Snowflake rejects requests without one. --compressed matters for result partitions, which come back with Content-Encoding: gzip.)

Sanity check — confirm the account identifier is right and the workspace is wired up: