Snowflake stage API

openapi: 3.2.0
info:
  title: Snowflake Stage API
  version: 0.0.1
  contact:
    name: Snowflake, Inc.
    url: https://snowflake.com
    email: support@snowflake.com
  description: 'Operations tagged stage across 2 of this provider''s published API definitions: stage.yaml, stage.yaml. Each path carries the servers of the definition it was published in.'
servers:
- description: Snowflake Stage API
  url: https://org-account.snowflakecomputing.com
tags:
- name: stage
paths:
  /api/v2/databases/{database}/schemas/{schema}/stages:
    get:
      summary: List Stages
      tags:
      - stage
      description: Lists stages under the database and schema, with show options as query parameters.
      operationId: listStages
      parameters:
      - $ref: common.yaml#/components/parameters/database
      - $ref: common.yaml#/components/parameters/schema
      - $ref: common.yaml#/components/parameters/like
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
            Link:
              $ref: common.yaml#/components/headers/Link
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Stage'
              examples:
                Liststages200Example:
                  summary: Default listStages 200 response
                  x-microcks-default: true
                  value:
                  - name: {}
                    kind: PERMANENT
                    url: https://www.example.com
                    endpoint: example_value
                    storage_integration: {}
                    comment: example_value
                    credentials:
                      credential_type: example_value
                    encryption:
                      type: SNOWFLAKE_FULL
                      master_key: example_value
                      kms_key_id: '500123'
                    directory_table:
                      enable: true
                      refresh_on_create: true
                      auto_refresh: true
                      notification_integration: example_value
                    created_on: '2026-01-15T10:30:00Z'
                    has_credentials: true
                    has_encryption_key: true
                    owner: example_value
                    owner_role_type: example_value
                    region: example_value
                    cloud: example_value
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - KeyPair: []
      - ExternalOAuth: []
      - SnowflakeOAuth: []
    post:
      summary: Create a Stage
      tags:
      - stage
      description: Create a stage, with standard create modifiers as query parameters. See the Stage component definition for what is required to be provided in the request body.
      operationId: createStage
      parameters:
      - $ref: common.yaml#/components/parameters/database
      - $ref: common.yaml#/components/parameters/schema
      - $ref: common.yaml#/components/parameters/createMode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Stage'
            examples:
              CreatestageRequestExample:
                summary: Default createStage request
                x-microcks-default: true
                value:
                  name: {}
                  kind: PERMANENT
                  url: https://www.example.com
                  endpoint: example_value
                  storage_integration: {}
                  comment: example_value
                  credentials:
                    credential_type: example_value
                  encryption:
                    type: SNOWFLAKE_FULL
                    master_key: example_value
                    kms_key_id: '500123'
                  directory_table:
                    enable: true
                    refresh_on_create: true
                    auto_refresh: true
                    notification_integration: example_value
                  created_on: '2026-01-15T10:30:00Z'
                  has_credentials: true
                  has_encryption_key: true
                  owner: example_value
                  owner_role_type: example_value
                  region: example_value
                  cloud: example_value
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - KeyPair: []
      - ExternalOAuth: []
      - SnowflakeOAuth: []
    servers:
    - description: Snowflake Stage API
      url: https://org-account.snowflakecomputing.com
  /api/v2/databases/{database}/schemas/{schema}/stages/{name}:
    get:
      summary: Fetch a Stage
      tags:
      - stage
      description: Fetch a stage using the describe command output.
      operationId: fetchStage
      parameters:
      - $ref: common.yaml#/components/parameters/database
      - $ref: common.yaml#/components/parameters/schema
      - $ref: common.yaml#/components/parameters/name
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
            Link:
              $ref: common.yaml#/components/headers/Link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stage'
              examples:
                Fetchstage200Example:
                  summary: Default fetchStage 200 response
                  x-microcks-default: true
                  value:
                    name: {}
                    kind: PERMANENT
                    url: https://www.example.com
                    endpoint: example_value
                    storage_integration: {}
                    comment: example_value
                    credentials:
                      credential_type: example_value
                    encryption:
                      type: SNOWFLAKE_FULL
                      master_key: example_value
                      kms_key_id: '500123'
                    directory_table:
                      enable: true
                      refresh_on_create: true
                      auto_refresh: true
                      notification_integration: example_value
                    created_on: '2026-01-15T10:30:00Z'
                    has_credentials: true
                    has_encryption_key: true
                    owner: example_value
                    owner_role_type: example_value
                    region: example_value
                    cloud: example_value
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - KeyPair: []
      - ExternalOAuth: []
      - SnowflakeOAuth: []
    delete:
      parameters:
      - $ref: common.yaml#/components/parameters/database
      - $ref: common.yaml#/components/parameters/schema
      - $ref: common.yaml#/components/parameters/name
      - $ref: common.yaml#/components/parameters/ifExists
      summary: Delete a Stage
      tags:
      - stage
      description: Delete a stage with the stage name. If ifExists is used, the operation will succeed even if the object does not exist. Otherwise, there will be a failure if the drop is unsuccessful.
      operationId: deleteStage
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - KeyPair: []
      - ExternalOAuth: []
      - SnowflakeOAuth: []
    servers:
    - description: Snowflake Stage API
      url: https://org-account.snowflakecomputing.com
  /api/v2/databases/{database}/schemas/{schema}/stages/{name}/files:
    get:
      summary: List Files in the Stage.
      tags:
      - stage
      description: List files in the stage -- this is equivalent to LIST @stage.
      operationId: listFiles
      parameters:
      - $ref: common.yaml#/components/parameters/database
      - $ref: common.yaml#/components/parameters/schema
      - $ref: common.yaml#/components/parameters/name
      - $ref: common.yaml#/components/parameters/pattern
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
            Link:
              $ref: common.yaml#/components/headers/Link
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StageFile'
              examples:
                Listfiles200Example:
                  summary: Default listFiles 200 response
                  x-microcks-default: true
                  value:
                  - name: Example Title
                    size: example_value
                    md5: example_value
                    last_modified: example_value
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - KeyPair: []
      - ExternalOAuth: []
      - SnowflakeOAuth: []
    servers:
    - description: Snowflake Stage API
      url: https://org-account.snowflakecomputing.com
  /api/v2/databases/{database}/schemas/{schema}/stages/{name}/files/{filePath}:presigned-url:
    post:
      summary: Generate a Presigned Url and Optionally Encryption Materials.
      tags:
      - stage
      description: Generate a presigned url and optionally encryption materials for uploading and downloading files.
      operationId: getPresignedUrl
      parameters:
      - $ref: common.yaml#/components/parameters/database
      - $ref: common.yaml#/components/parameters/schema
      - $ref: common.yaml#/components/parameters/name
      - name: filePath
        description: The full stage path of the file.
        in: path
        required: true
        schema:
          type: string
        example: example_value
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresignedUrlRequest'
            examples:
              GetpresignedurlRequestExample:
                summary: Default getPresignedUrl request
                x-microcks-default: true
                value:
                  expiration_time: 10
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileTransferMaterial'
              examples:
                Getpresignedurl200Example:
                  summary: Default getPresignedUrl 200 response
                  x-microcks-default: true
                  value:
                    presigned_url: https://www.example.com
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - KeyPair: []
      - ExternalOAuth: []
      - SnowflakeOAuth: []
    servers:
    - description: Snowflake Stage API
      url: https://org-account.snowflakecomputing.com
components:
  schemas:
    Credentials:
      type: object
      description: Specifies the credentials of the stage.
      properties:
        credential_type:
          description: Type of the credential, can be either AWS or AZURE.
          type: string
          example: example_value
      discriminator:
        propertyName: credential_type
        mapping:
          AWS: AwsCredentials
          AZURE: AzureCredentials
    PresignedUrlRequest:
      type: object
      description: Request object to get presigned url of a file
      properties:
        expiration_time:
          description: Expiration time of the generated presigned url in seconds.
          type: integer
          example: 10
    StageFile:
      type: object
      description: A file on a snowflake stage.
      properties:
        name:
          type: string
          description: Name of the file.
          example: Example Title
        size:
          type: string
          description: Size of the file.
          readOnly: true
          example: example_value
        md5:
          type: string
          description: md5 hash of the file.
          readOnly: true
          example: example_value
        last_modified:
          type: string
          description: Date and time when the file was last modified.
          readOnly: true
          example: example_value
    FileTransferMaterial:
      type: object
      description: Materials for uploading and downloading stage files
      properties:
        presigned_url:
          type: string
          description: Presigned url for file transfer, only works for Server Side Encrypted Stages.
          example: https://www.example.com
    Stage:
      type: object
      description: A Snowflake stage.
      properties:
        name:
          $ref: ./common.yaml#/components/schemas/Identifier
          description: String that specifies the identifier (i.e. name) for the stage.
        kind:
          type: string
          enum:
          - PERMANENT
          - TEMPORARY
          default: PERMANENT
          description: Specifies whether the stage is permanent or temporary.
          example: PERMANENT
        url:
          type: string
          description: URL for the external stage; blank for an internal stage.
          example: https://www.example.com
        endpoint:
          type: string
          description: The S3-compatible API endpoint associated with the stage; always NULL for stages that are not S3-compatible.
          example: example_value
        storage_integration:
          $ref: ./common.yaml#/components/schemas/Identifier
          description: Storage integration associated with the stage; always NULL for an internal stage.
        comment:
          type: string
          description: Specifies a comment for the stage.
          example: example_value
        credentials:
          $ref: '#/components/schemas/Credentials'
          writeOnly: true
          description: Credentials of the stage.
        encryption:
          type: object
          description: Encryption parameters of the stage.
          writeOnly: true
          properties:
            type:
              type: string
              enum:
              - SNOWFLAKE_FULL
              - SNOWFLAKE_SSE
              - AWS_CSE
              - AWS_SSE_S3
              - AWS_SSE_KMS
              - GCS_SSE_KMS
              - AZURE_CSE
              - NONE
              description: Specifies the encryption type used.
            master_key:
              type: string
              format: password
              description: Specifies the client-side master key used to encrypt the files in the bucket. The master key must be a 128-bit or 256-bit key in Base64-encoded form.
            kms_key_id:
              type: string
              description: Optionally specifies the ID for the KMS-managed key used to encrypt files unloaded into the bucket.
          example: example_value
        directory_table:
          type: object
          description: Directory table parameters of the stage.
          properties:
            enable:
              type: boolean
              default: false
              description: Specifies whether to add a directory table to the stage. When the value is TRUE, a directory table is created with the stage.
            refresh_on_create:
              type: boolean
              default: true
              writeOnly: true
              description: Specifies whether to automatically refresh the directory table metadata once, immediately after the stage is created.
            auto_refresh:
              type: boolean
              default: false
              writeOnly: true
              description: Specifies whether Snowflake should enable triggering automatic refreshes of the directory table metadata when new or updated data files are available in the named external stage specified in the URL value.
            notification_integration:
              type: string
              writeOnly: true
              description: Specifies the name of the notification integration used to automatically refresh the directory table metadata.
          example: example_value
        created_on:
          type: string
          description: Date and time when the stage was created.
          format: date-time
          readOnly: true
          example: '2026-01-15T10:30:00Z'
        has_credentials:
          type: boolean
          description: Indicates that the external stage has access credentials; always false for an internal stage.
          readOnly: true
          example: true
        has_encryption_key:
          type: boolean
          description: Indicates that the external stage contains encrypted files; always false for an internal stage.
          readOnly: true
          example: true
        owner:
          type: string
          description: Role that owns the stage.
          readOnly: true
          example: example_value
        owner_role_type:
          type: string
          description: The type of role that owns the object, either ROLE or DATABASE_ROLE. If a Snowflake Native App owns the object, the value is APPLICATION. Snowflake returns NULL if you delete the object because a deleted object does not have an owner role.
          readOnly: true
          example: example_value
        region:
          type: string
          description: Region where the stage is located.
          readOnly: true
          example: example_value
        cloud:
          type: string
          description: Cloud provider; always NULL for an internal stage.
          readOnly: true
          example: example_value
      example:
        name: stage_name
      required:
      - name
    Credentials_2:
      type: object
      description: Specifies the credentials of the stage.
      properties:
        credential_type:
          description: Type of the credential, can be either AWS or AZURE.
          type: string
      discriminator:
        propertyName: credential_type
        mapping:
          AWS: AwsCredentials
          AZURE: AzureCredentials
    PresignedUrlRequest_2:
      type: object
      description: Request object to get presigned url of a file
      properties:
        expiration_time:
          description: Expiration time of the generated presigned url in seconds.
          type: integer
    StageFile_2:
      type: object
      description: A file on a snowflake stage.
      properties:
        name:
          type: string
          description: Name of the file.
        size:
          type: string
          description: Size of the file.
          readOnly: true
        md5:
          type: string
          description: md5 hash of the file.
          readOnly: true
        last_modified:
          type: string
          description: Date and time when the file was last modified.
          readOnly: true
    FileTransferMaterial_2:
      type: object
      description: Materials for uploading and downloading stage files
      properties:
        presigned_url:
          type: string
          description: Presigned url for file transfer, only works for Server Side Encrypted Stages.
    Stage_2:
      type: object
      description: A Snowflake stage.
      properties:
        name:
          $ref: ./common.yaml#/components/schemas/Identifier
          description: String that specifies the identifier (i.e. name) for the stage.
        kind:
          type: string
          enum:
          - PERMANENT
          - TEMPORARY
          default: PERMANENT
          description: Specifies whether the stage is permanent or temporary.
        url:
          type: string
          description: URL for the external stage; blank for an internal stage.
        endpoint:
          type: string
          description: The S3-compatible API endpoint associated with the stage; always NULL for stages that are not S3-compatible.
        storage_integration:
          $ref: ./common.yaml#/components/schemas/Identifier
          description: Storage integration associated with the stage; always NULL for an internal stage.
        comment:
          type: string
          description: Specifies a comment for the stage.
        credentials:
          $ref: '#/components/schemas/Credentials_2'
          writeOnly: true
          description: Credentials of the stage.
        encryption:
          type: object
          description: Encryption parameters of the stage.
          writeOnly: true
          properties:
            type:
              type: string
              enum:
              - SNOWFLAKE_FULL
              - SNOWFLAKE_SSE
              - AWS_CSE
              - AWS_SSE_S3
              - AWS_SSE_KMS
              - GCS_SSE_KMS
              - AZURE_CSE
              - NONE
              description: Specifies the encryption type used.
            master_key:
              type: string
              format: password
              description: Specifies the client-side master key used to encrypt the files in the bucket. The master key must be a 128-bit or 256-bit key in Base64-encoded form.
            kms_key_id:
              type: string
              description: Optionally specifies the ID for the KMS-managed key used to encrypt files unloaded into the bucket.
        directory_table:
          type: object
          description: Directory table parameters of the stage.
          properties:
            enable:
              type: boolean
              default: false
              description: Specifies whether to add a directory table to the stage. When the value is TRUE, a directory table is created with the stage.
            refresh_on_create:
              type: boolean
              default: true
              description: Specifies whether to automatically refresh the directory table metadata once, immediately after the stage is created.
            auto_refresh:
              type: boolean
              default: false
              description: Specifies whether Snowflake should enable triggering automatic refreshes of the directory table metadata when new or updated data files are available in the named external stage specified in the URL value.
            notification_integration:
              type: string
              description: Specifies the name of the notification integration used to automatically refresh the directory table metadata.
        created_on:
          type: string
          description: Date and time when the stage was created.
          format: date-time
          readOnly: true
        has_credentials:
          type: boolean
          description: Indicates that the external stage has access credentials; always false for an internal stage.
          readOnly: true
        has_encryption_key:
          type: boolean
          description: Indicates that the external stage contains encrypted files; always false for an internal stage.
          readOnly: true
        owner:
          type: string
          description: Role that owns the stage.
          readOnly: true
        owner_role_type:
          type: string
          description: The type of role that owns the object, either ROLE or DATABASE_ROLE. If a Snowflake Native App owns the object, the value is APPLICATION. Snowflake returns NULL if you delete the object because a deleted object does not have an owner role.
          readOnly: true
        region:
          type: string
          description: Region where the stage is located.
          readOnly: true
        cloud:
          type: string
          description: Cloud provider; always NULL for an internal stage.
          readOnly: true
      example:
        name: stage_name
      required:
      - name
  securitySchemes:
    KeyPair:
      $ref: common.yaml#/components/securitySchemes/KeyPair
    ExternalOAuth:
      $ref: common.yaml#/components/securitySchemes/ExternalOAuth
    SnowflakeOAuth:
      $ref: common.yaml#/components/securitySchemes/SnowflakeOAuth
    ProgrammaticAccessToken:
      $ref: common.yaml#/components/securitySchemes/ProgrammaticAccessToken
x-refined-from:
- stage.yaml
- stage.yaml