openapi: 3.0.0
info:
  title: Stripe Files API
  description: >-
    This object represents files hosted on Stripe's servers. You can upload
    files with the create file request (for example, when uploading dispute
    evidence). Stripe also creates files independently (for example, the results
    of a Sigma scheduled query).
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
security:
  - basicAuth: []
  - bearerAuth: []
servers:
  - url: https://api.stripe.com/
paths:
  /v1/files:
    get:
      description: >-
        <p>Returns a list of the files that your account has access to. Stripe
        sorts and returns the files by their creation dates, placing the most
        recently created files at the top.</p>
      operationId: getFiles
      parameters:
        - explode: true
          in: query
          name: created
          required: false
          schema:
            anyOf:
              - properties:
                  gt:
                    type: integer
                  gte:
                    type: integer
                  lt:
                    type: integer
                  lte:
                    type: integer
                title: range_query_specs
                type: object
              - type: integer
          style: deepObject
        - description: >-
            A cursor for use in pagination. `ending_before` is an object ID that
            defines your place in the list. For instance, if you make a list
            request and receive 100 objects, starting with `obj_bar`, your
            subsequent call can include `ending_before=obj_bar` in order to
            fetch the previous page of the list.
          in: query
          name: ending_before
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
        - description: >-
            A limit on the number of objects to be returned. Limit can range
            between 1 and 100, and the default is 10.
          in: query
          name: limit
          required: false
          schema:
            type: integer
          style: form
        - description: >-
            Filter queries by the file purpose. If you don't provide a purpose,
            the queries return unfiltered files.
          in: query
          name: purpose
          required: false
          schema:
            enum:
              - account_requirement
              - additional_verification
              - business_icon
              - business_logo
              - customer_signature
              - dispute_evidence
              - document_provider_identity_document
              - finance_report_run
              - identity_document
              - identity_document_downloadable
              - pci_document
              - selfie
              - sigma_scheduled_query
              - tax_document_user_upload
              - terminal_reader_splashscreen
            maxLength: 5000
            type: string
            x-stripeBypassValidation: true
          style: form
        - description: >-
            A cursor for use in pagination. `starting_after` is an object ID
            that defines your place in the list. For instance, if you make a
            list request and receive 100 objects, ending with `obj_foo`, your
            subsequent call can include `starting_after=obj_foo` in order to
            fetch the next page of the list.
          in: query
          name: starting_after
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetFilesRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                  - data
                $ref: '#/components/schemas/FileResourceFileList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Files
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Files
        - Get
    post:
      description: >-
        <p>To upload a file to Stripe, you need to send a request of type
        <code>multipart/form-data</code>. Include the file you want to upload in
        the request, and the parameters for creating a file.</p>


        <p>All of Stripe’s officially supported Client libraries support sending
        <code>multipart/form-data</code>.</p>
      operationId: postFiles
      requestBody:
        content:
          multipart/form-data:
            encoding:
              expand:
                explode: true
                style: deepObject
              file_link_data:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostFilesRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      servers:
        - url: https://files.stripe.com/
      summary: Stripe Post   Files
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Files
        - Post
  /v1/files/{file}:
    get:
      description: >-
        <p>Retrieves the details of an existing file object. After you supply a
        unique file ID, Stripe returns the corresponding file object. Learn how
        to <a href="/docs/file-upload#download-file-contents">access file
        contents</a>.</p>
      operationId: getFilesFile
      parameters:
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
        - in: path
          name: file
          required: true
          schema:
            maxLength: 5000
            type: string
          style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetFilesFileRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Files File
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Files
        - Get
components:
  schemas:
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
        - error
      type: object
    file:
      description: >-
        This object represents files hosted on Stripe's servers. You can upload

        files with the [create file](https://stripe.com/docs/api#create_file)
        request

        (for example, when uploading dispute evidence). Stripe also

        creates files independently (for example, the results of a [Sigma
        scheduled

        query](#scheduled_queries)).


        Related guide: [File upload guide](https://stripe.com/docs/file-upload)
      properties:
        created:
          description: >-
            Time at which the object was created. Measured in seconds since the
            Unix epoch.
          format: unix-time
          type: integer
        expires_at:
          description: The file expires and isn't available at this time in epoch seconds.
          format: unix-time
          nullable: true
          type: integer
        filename:
          description: The suitable name for saving the file to a filesystem.
          maxLength: 5000
          nullable: true
          type: string
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        links:
          description: >-
            A list of [file links](https://stripe.com/docs/api#file_links) that
            point at this file.
          nullable: true
          properties:
            data:
              description: Details about each object.
              items:
                $ref: '#/components/schemas/file_link'
              type: array
            has_more:
              description: >-
                True if this list has another page of items after this one that
                can be fetched.
              type: boolean
            object:
              description: >-
                String representing the object's type. Objects of the same type
                share the same value. Always has the value `list`.
              enum:
                - list
              type: string
            url:
              description: The URL where this list can be accessed.
              maxLength: 5000
              pattern: ^/v1/file_links
              type: string
          required:
            - data
            - has_more
            - object
            - url
          title: FileResourceFileLinkList
          type: object
          x-expandableFields:
            - data
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - file
          type: string
        purpose:
          description: >-
            The [purpose](https://stripe.com/docs/file-upload#uploading-a-file)
            of the uploaded file.
          enum:
            - account_requirement
            - additional_verification
            - business_icon
            - business_logo
            - customer_signature
            - dispute_evidence
            - document_provider_identity_document
            - finance_report_run
            - identity_document
            - identity_document_downloadable
            - pci_document
            - selfie
            - sigma_scheduled_query
            - tax_document_user_upload
            - terminal_reader_splashscreen
          type: string
          x-stripeBypassValidation: true
        size:
          description: The size of the file object in bytes.
          type: integer
        title:
          description: A suitable title for the document.
          maxLength: 5000
          nullable: true
          type: string
        type:
          description: The returned file type (for example, `csv`, `pdf`, `jpg`, or `png`).
          maxLength: 5000
          nullable: true
          type: string
        url:
          description: Use your live secret API key to download the file from this URL.
          maxLength: 5000
          nullable: true
          type: string
      required:
        - created
        - id
        - object
        - purpose
        - size
      title: File
      type: object
      x-expandableFields:
        - links
      x-resourceId: file
    GetFilesRequest:
      type: object
      properties: {}
    FileResourceFileList:
      type: object
      required:
        - data
        - has_more
        - object
        - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/file'
          type: array
        has_more:
          description: >-
            True if this list has another page of items after this one that can
            be fetched.
          type: boolean
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value. Always has the value `list`.
          enum:
            - list
          type: string
        url:
          description: The URL where this list can be accessed.
          maxLength: 5000
          pattern: ^/v1/files
          type: string
    PostFilesRequest:
      type: object
      required:
        - file
        - purpose
      properties:
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        file:
          description: >-
            A file to upload. Make sure that the specifications follow RFC 2388,
            which defines file transfers for the `multipart/form-data` protocol.
          format: binary
          type: string
        file_link_data:
          description: >-
            Optional parameters that automatically create a [file
            link](https://stripe.com/docs/api#file_links) for the newly created
            file.
          properties:
            create:
              type: boolean
            expires_at:
              format: unix-time
              type: integer
            metadata:
              anyOf:
                - additionalProperties:
                    type: string
                  type: object
                - enum:
                    - ''
                  type: string
          required:
            - create
          title: file_link_creation_params
          type: object
        purpose:
          description: >-
            The [purpose](https://stripe.com/docs/file-upload#uploading-a-file)
            of the uploaded file.
          enum:
            - account_requirement
            - additional_verification
            - business_icon
            - business_logo
            - customer_signature
            - dispute_evidence
            - identity_document
            - pci_document
            - tax_document_user_upload
            - terminal_reader_splashscreen
          type: string
          x-stripeBypassValidation: true
    GetFilesFileRequest:
      type: object
      properties: {}
  securitySchemes:
    basicAuth:
      description: >-
        Basic HTTP authentication. Allowed headers-- Authorization: Basic
        <api_key> | Authorization: Basic <base64 hash of `api_key:`>
      scheme: basic
      type: http
    bearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
tags:
  - name: Files
  - name: Get
  - name: Post