Snowpipe Streaming API REST endpoints¶

The following request headers apply to all the endpoints for the Snowpipe Streaming REST API:

Header	Description
`Authorization`	auth token
`X-Snowflake-Authorization-Token-Type` (optional)	JWT/OAuth

Get Hostname¶

The Get Hostname returns the hostname used to interact with the Snowpipe Streaming REST API. Each account has a unique hostname.

GET /v2/streaming/hostname

Response:

Field	Type	Description
status_code	int	Status code that customers can use to map internal errors with public documentation.
message	string	Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.
hostname	string	The rowset hostname of the account.

Exchange Rowset Scoped Token¶

The Exchange Rowset Scoped Token returns a security token that can be used to access only the Snowpipe Streaming API-related service. This provides security protection for the customer.

POST /oauth/token

Request:

Attribute	Required	Component	Description
content_type	Yes	Header	“application/x-www-form-urlencoded”
grant_type	Yes	payload	“urn:ietf:params:oauth:grant-type:jwt-bearer”
scope	Yes	payload	The rowset hostname of the account

Response:

Field	Type	Description
status_code	int	Status code that customers can use to map internal errors with public documentation.
message	string	Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.
token	string	The rowset scoped token.

Open Channel¶

The Open Channel operation creates or opens a new channel against a pipe or table. If the channel already exists, Snowflake bumps the client sequencer of the channel and returns the last committed offset token.

PUT /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

Request:

Attribute	Required	Component	Description
databaseName	Yes	URI	Database name, case-insensitive
schemaName	Yes	URI	Schema name, case-insensitive
pipeName	Yes	URI	Pipe name, case-insensitive
channelName	Yes	URI	The name of the channel that you create or re-open, case-insensitive
offset_token	No	payload	String used to set an offset token when opening a channel.
requestId	No	Query parameter	UUID used to track requests through the system

Response:

Field	Type	Description
channel_status_code	String	Indicating the status of the channel.
last_committed_offset_token	String	Latest committed offset token
database_name	String	The name of the database that the channel belongs to.
schema_name	String	The name of the schema that the channel belongs to.
pipe_name	String	The name of the pipe that the channel belongs to.
channel_name	String	The name of the channel.
rows_inserted	int	A count of all rows inserted into this channel.
rows_parsed	int	A count of all rows parsed, but not necessarily inserted into this channel.
rows_errors	int	A count of all rows that experienced errors when inserting into this channel and were therefore rejected.
last_error_offset_upper_bound	String	Upper bound for the latest offset token of the inserted row set that has the last corresponding to an error. The real offset token of the row set with the last error is either this one or strictly before it in the channel ingestion order.
last_error_message	String	A human readable message corresponding to the latest error code for that channel, with sensitive customer data redacted.
last_error_timestamp	timestamp_utc	Timestamp at which the last error occured.
snowflake_avg_processing_latency_ms	int	Average e2e processing time for this channel.

Append Row(s)¶

The Append Rows operation inserts a batch of rows to the given channel.

POST /v2/streaming/data/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}/rows

Request:

Attribute	Required	Component	Description
databaseName	Yes	URI	Database name, case-insensitive
schemaName	Yes	URI	Schema name, case-insensitive
pipeName	Yes	URI	Pipe, case-insensitive
channelName	Yes	URI	Channel name, case-insensitive
continuationToken	Yes	Query parameter	Continuation token from Snowflake, encapsulates both client and row sequencers
offsetToken	No	Query parameter	String used to set an offset token per batch.
rows	Yes	payload	Actual data payload that will be ingested in NDJSON format.
requestId	No	Query parameter	A UUID used to track requests through the system.

Response:

Field	Type	Description
status_code	int	Status code that customers can use to map internal errors with public documentation
next_continuation_token	string	The next continuation token from Snowflake, which encapsulates both client and row sequencers. It should be used for inserting the next batch.
message	string	Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.

Drop Channel¶

The Drop Channel operation drops a channel at server side along with its metadata.

DELETE /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

Request:

Attribute	Required	Component	Description
databaseName	Yes	URI	Database name, case-insensitive
schemaName	Yes	URI	Schema name, case-insensitive
pipeOrTableName	Yes	URI	Pipe or table name, case-insensitive
channelName	Yes	URI	Channel name, case-insensitive
continuationToken	No	payload	Continuation token from Snowflake, which encapsulates both client and row sequencers. If it’s not provided, then we will delete the channel with the latest client sequencer.
requestId	No	Query parameter	A UUID used to track requests through the system

Response:

Field	Type	Description
status_code	int	Status code that customers can use to map internal errors with public documentation
message	string	Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.

Bulk Get Channel Status¶

The Bulk Get Channel Status operation returns the status of a channel for a specific client sequencer.

POST /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}:bulk-channel-status

Request:

Attribute	Required	Component	Description
databaseName	Yes	URI	Database name, case-insensitive
schemaName	Yes	URI	Schema name, case-insensitive
pipeName	Yes	URI	Pipe name, case-insensitive
channel_names	Yes	Payload	An array of String channel names that the customer wants to get status for; the names are case-sensitive. For example, `{"channel_names":["channel1", "channel2"]}`.

Response:

Field	Type	Description
channel_status_code	String	Indicating the status of the channel.
last_committed_offset_token	String	Latest committed offset token
database_name	String	The name of the database that the channel belongs to.
schema_name	String	The name of the schema that the channel belongs to.
pipe_name	String	The name of the pipe that the channel belongs to.
channel_name	String	The name of the channel.
rows_inserted	int	A count of all rows inserted into this channel.
rows_parsed	int	A count of all rows parsed, but not necessarily inserted into this channel.
rows_errors	int	A count of all rows that experienced errors when inserting into this channel and were therefore rejected.
last_error_offset_upper_bound	String	Upper bound for the latest offset token of the inserted row set that has the last corresponding to an error. The real offset token of the row set with the last error is either this one or strictly before it in the channel ingestion order.
last_error_message	String	A human readable message corresponding to the latest error code for that channel, with sensitive customer data redacted.
last_error_timestamp	timestamp_utc	Timestamp at which the last error occured.
snowflake_avg_processing_latency_ms	int	Average e2e processing time for this channel.