Stripe Files API

openapi: 3.2.0
info:
  title: Stripe Files API
  description: Needs description.
  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
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Files
paths:
  /v1/files:
    get:
      description: 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.
      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.
      tags:
      - Files
      summary: Get files
      x-summary-source: derived
    post:
      description: 'To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.


        All of Stripe’s officially supported Client libraries support sending multipart/form-data.'
      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/
      tags:
      - Files
      summary: Post files
      x-summary-source: derived
  /v1/files/{file}:
    get:
      description: Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to access file contents.
      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.
      tags:
      - Files
      summary: Get files file
      x-summary-source: derived
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
          type:
          - integer
          - 'null'
        filename:
          description: The suitable name for saving the file to a filesystem.
          maxLength: 5000
          type:
          - string
          - 'null'
        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.
          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
          - 'null'
          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
          type:
          - string
          - 'null'
        type:
          description: The returned file type (for example, `csv`, `pdf`, `jpg`, or `png`).
          maxLength: 5000
          type:
          - string
          - 'null'
        url:
          description: Use your live secret API key to download the file from this URL.
          maxLength: 5000
          type:
          - string
          - 'null'
      required:
      - created
      - id
      - object
      - purpose
      - size
      title: File
      type: object
      x-expandableFields:
      - links
      x-resourceId: file
    GetFilesFileRequest:
      type: object
      properties: {}
    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
    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
    GetFilesRequest:
      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