openapi: 3.0.0
info:
  title: Soracom and Query Analysis FileEntry API
  description: Run SQL queries against Soracom Query, fetch query schemas, and search SIMs, Inventory devices, and Sigfox devices.
  version: 20250903-043502
servers:
- description: Japan coverage production API endpoint
  url: https://api.soracom.io/v1
- description: Global coverage production API endpoint
  url: https://g.api.soracom.io/v1
tags:
- description: '[Soracom Harvest Files](/en/docs/harvest/)'
  name: FileEntry
paths:
  /files:
    get:
      description: Returns a list of file entries which beginnings of their file paths are matched with the `prefix` query string in the ascending sorted UTF-8 bytes order of their file paths. An empty list is returned if the prefix does not match with any paths of file entries.
      operationId: findFiles
      parameters:
      - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files.
        in: query
        name: scope
        required: true
        schema:
          enum:
          - private
          - public
          type: string
      - description: Prefix to match with file path.
        in: query
        name: prefix
        required: true
        schema:
          type: string
      - description: Maximum number of file entries to be returned.
        in: query
        name: limit
        required: false
        schema:
          default: 10
          type: integer
      - description: The filePath of the last file entry retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next file entry onward.
        in: query
        name: last_evaluated_key
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FileEntry'
                type: array
          description: List of file entries found with query parameters. Empty list if there is no file entry matching prefix.
        '404':
          description: The specified scope does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Find files with prefix query parameter in the scope
      tags:
      - FileEntry
      x-soracom-cli:
      - files find
      x-soracom-cli-pagination:
        request:
          param: last_evaluated_key
        response:
          header: x-soracom-next-key
  /files/{scope}/{path}:
    delete:
      description: Deletes the file specified by scope and path. Only `private` scope is allowed for the operation.
      operationId: deleteFile
      parameters:
      - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files.
        in: path
        name: scope
        required: true
        schema:
          default: private
          enum:
          - private
          type: string
      - description: Target path.
        in: path
        name: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The specified file is successfully deleted.
        '404':
          description: No such file.
      security:
      - api_key: []
        api_token: []
      summary: Deletes the file specified by scope and path.
      tags:
      - FileEntry
      x-soracom-cli:
      - files delete
    get:
      description: Download file specified by the path and the scope. Note that [FileEntry:listFiles API](#!/FileEntry/listFiles) will be called if the path ends with `/`.
      operationId: getFile
      parameters:
      - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files.
        in: path
        name: scope
        required: true
        schema:
          default: private
          enum:
          - private
          - public
          type: string
      - description: Target path.
        in: path
        name: path
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Redirection to a link to download a file. If the specified path is a directory, redirection to the listFiles API.
        '404':
          description: No such file.
      security:
      - api_key: []
        api_token: []
      summary: Download file specified by the path and the scope
      tags:
      - FileEntry
      x-soracom-cli:
      - files get
    head:
      description: Gets the metadata of the file specified by the path and the scope.
      operationId: getFileMetadata
      parameters:
      - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files.
        in: path
        name: scope
        required: true
        schema:
          default: private
          enum:
          - private
          - public
          type: string
      - description: Target path.
        in: path
        name: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Metadata of the file
          headers:
            Content-Length:
              description: File size (bytes)
              schema:
                type: integer
            Content-Type:
              description: File's Content-Type
              schema:
                type: string
            ETag:
              description: Identifier representing the file version
              schema:
                type: string
        '404':
          description: No such file.
      security:
      - api_key: []
        api_token: []
      summary: Gets the metadata of the file specified by the path and the scope
      tags:
      - FileEntry
      x-soracom-cli:
      - files get-metadata
    put:
      description: Uploads the file to the specified path in the scope. Only `private` scope is allowed for the operation.
      operationId: putFile
      parameters:
      - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files.
        in: path
        name: scope
        required: true
        schema:
          default: private
          enum:
          - private
          type: string
      - description: Target path.
        in: path
        name: path
        required: true
        schema:
          type: string
      - description: Content-Type of the file to be uploaded.
        in: header
        name: content-type
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              format: binary
              type: string
        description: Contents of the file to be updated.
        required: true
      responses:
        '200':
          description: File is successfully updated with the content.
        '201':
          description: File is successfully created.
      security:
      - api_key: []
        api_token: []
      summary: Uploads the file to the specified path in the scope.
      tags:
      - FileEntry
      x-soracom-cli:
      - files put
  /files/{scope}/{path}/:
    delete:
      description: Deletes the directory specified by scope and path. Only `private` scope is allowed for the operation.
      operationId: deleteDirectory
      parameters:
      - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files.
        in: path
        name: scope
        required: true
        schema:
          default: private
          enum:
          - private
          type: string
      - description: Target path.
        in: path
        name: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The specified directory is successfully deleted.
        '400':
          description: The specified directory is not empty.
        '404':
          description: No such directory.
      security:
      - api_key: []
        api_token: []
      summary: Deletes the directory specified by scope and path
      tags:
      - FileEntry
      x-soracom-cli:
      - files delete-directory
    get:
      description: 'Returns files and directories from the directory specified by the scope and path. Note that [FileEntry:getFile API](#!/FileEntry/getFile) will be called if the path does not end in `/`. If the total number of entries does not fit in one page, a URL for accessing the next page is returned in the `link` header of the response.

        '
      operationId: listFiles
      parameters:
      - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files.
        in: path
        name: scope
        required: true
        schema:
          default: private
          enum:
          - private
          - public
          type: string
      - description: Target path.
        in: path
        name: path
        required: true
        schema:
          default: /
          type: string
      - description: Maximum number of file entries to be returned.
        in: query
        name: limit
        required: false
        schema:
          default: 10
          type: integer
      - description: The filename of the last file entry retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next file entry onward.
        in: query
        name: last_evaluated_key
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FileEntry'
                type: array
          description: Files and directories from the directory specified by the scope and path.
        '404':
          description: No such directory.
      security:
      - api_key: []
        api_token: []
      summary: Returns files and directories from the directory specified by the scope and path.
      tags:
      - FileEntry
      x-soracom-cli:
      - files list
      x-soracom-cli-pagination:
        request:
          param: last_evaluated_key
        response:
          header: x-soracom-next-key
components:
  schemas:
    FileEntry:
      properties:
        contentLength:
          description: Content length of the file.
          format: int64
          type: integer
        contentType:
          description: Content type of the file.
          type: string
        createdTime:
          description: Created time of the file.
          format: int64
          type: integer
        directory:
          description: Parent directory name.
          type: string
        etag:
          description: ETag of the file.
          type: string
        filePath:
          description: Absolute path of the file.
          type: string
        filename:
          description: File name.
          type: string
        isDirectory:
          description: Whether the entry is directory or not.
          type: boolean
        lastModifiedTime:
          description: Last modified time of the file.
          format: int64
          type: integer
      type: object
  securitySchemes:
    api_key:
      description: 'API key for authentication. Obtain this from the Soracom User Console or via the Auth API.

        Required in combination with an API token for all authenticated requests.

        '
      in: header
      name: X-Soracom-API-Key
      type: apiKey
    api_token:
      description: 'API token for authentication. This token has an expiration time and must be refreshed periodically.

        Required in combination with an API key for all authenticated requests.'
      in: header
      name: X-Soracom-Token
      type: apiKey