v4

latestSwagger 2.02026-08-0343714211.7 MB

folders

Files

List Folders by Path

get/folders/{path}

Path parameters

pathstring required

Path to operate on.

Query parameters

cursorstring

Send cursor to resume an existing list from the point at which you left off. Get a cursor from an existing list via the X-Files-Cursor-Next header or the X-Files-Cursor-Prev header.

per_pageinteger

Number of records to show per page. (Max: 10000, 1,000 or less is recommended).

preview_sizestring

Request a preview size. Can be small (default), large, xlarge, or pdf.

Search by field and direction. Valid fields are path, size, modified_at_datetime, provided_modified_at. Valid directions are asc and desc. Defaults to {"path":"asc"}.

searchstring

If specified, will search the folders/files list by name. Ignores text before last /. This is the same API used by the search bar in the web UI when running 'Search This Folder'. Search results are a best effort, not real time, and not guaranteed to perfectly match the latest folder listing. Results may be truncated if more than 1,000 possible matches exist. This field should only be used for ad-hoc (human) searching, and not as part of an automated process.

search_custom_metadata_keystring

If provided, the search string in search will search for files where this custom metadata key matches the value sent in search. Set this to * to allow any metadata key to match the value sent in search.

search_allboolean

Search entire site? If true, we will search the entire site. Do not provide a path when using this parameter. This is the same API used by the search bar in the web UI when running 'Search All Files'. Search results are a best effort, not real time, and not guaranteed to match every file. This field should only be used for ad-hoc (human) searching, and not as part of an automated process.

with_previewsboolean

Include file previews?

with_priority_colorboolean

Include file priority color information?

typestring

Type of objects to return. Can be folder or file.

modified_at_datetimestring date-time

If provided, will only return files/folders modified after this time. Can be used only in combination with type filter.

Response

A list of Folders objects.

pathstring

File/Folder path

created_by_idinteger

User ID of the User who created the file/folder

created_by_api_key_idinteger

ID of the API key that created the file/folder

created_by_as2_incoming_message_idinteger

ID of the AS2 Incoming Message that created the file/folder

created_by_automation_idinteger

ID of the Automation that created the file/folder

created_by_bundle_registration_idinteger

ID of the Bundle Registration that created the file/folder

created_by_inbox_idinteger

ID of the Inbox that created the file/folder

created_by_remote_server_idinteger

ID of the Remote Server that created the file/folder

created_by_sync_idinteger

ID of the Sync that created the file/folder

custom_metadataobject

Custom metadata map of keys and values. Limited to 32 keys, 256 characters per key and 1024 characters per value.

display_namestring

File/Folder display name

typestring

Type: directory or file.

sizeinteger

File/Folder size

created_atstring date-time

File created date/time

last_modified_by_idinteger

User ID of the User who last modified the file/folder

last_modified_by_api_key_idinteger

ID of the API key that last modified the file/folder

last_modified_by_automation_idinteger

ID of the Automation that last modified the file/folder

last_modified_by_bundle_registration_idinteger

ID of the Bundle Registration that last modified the file/folder

last_modified_by_remote_server_idinteger

ID of the Remote Server that last modified the file/folder

last_modified_by_sync_idinteger

ID of the Sync that last modified the file/folder

mtimestring date-time

File last modified date/time, according to the server. This is the timestamp of the last Files.com operation of the file, regardless of what modified timestamp was sent.

provided_mtimestring date-time

File last modified date/time, according to the client who set it. Files.com allows desktop, FTP, SFTP, and WebDAV clients to set modified at times. This allows Desktop<->Cloud syncing to preserve modified at times.

crc32string

File CRC32 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.

md5string

File MD5 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.

sha1string

File SHA1 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.

sha256string

File SHA256 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.

mime_typestring

MIME Type. This is determined by the filename extension and is not stored separately internally.

regionstring

Region location

permissionsstring

A short string representing the current user's permissions. Can be r (Read),w (Write),d (Delete), l (List) or any combination

subfolders_locked?boolean

Are subfolders locked and unable to be modified?

is_lockedboolean

Is this folder locked and unable to be modified?

download_uristring

Link to download file. Provided only in response to a download request.

priority_colorstring

Bookmark/priority color of file/folder

preview_idinteger

File preview ID

Example response

[
  {
    "path": "path/file.txt",
    "created_by_id": 1,
    "created_by_api_key_id": 1,
    "created_by_as2_incoming_message_id": 1,
    "created_by_automation_id": 1,
    "created_by_bundle_registration_id": 1,
    "created_by_inbox_id": 1,
    "created_by_remote_server_id": 1,
    "created_by_sync_id": 1,
    "custom_metadata": {
      "key": "value"
    },
    "display_name": "file.txt",
    "type": "file",
    "size": 1024,
    "created_at": "2000-01-01T01:00:00Z",
    "last_modified_by_id": 1,
    "last_modified_by_api_key_id": 1,
    "last_modified_by_automation_id": 1,
    "last_modified_by_bundle_registration_id": 1,
    "last_modified_by_remote_server_id": 1,
    "last_modified_by_sync_id": 1,
    "mtime": "2000-01-01T01:00:00Z",
    "provided_mtime": "2000-01-01T01:00:00Z",
    "crc32": "70976923",
    "md5": "17c54824e9931a4688ca032d03f6663c",
    "sha1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "mime_type": "application/octet-stream",
    "region": "us-east-1",
    "permissions": "rwd",
    "subfolders_locked?": true,
    "is_locked": true,
    "download_uri": "https://mysite.files.com/...",
    "direct_connection_info": {
      "version": 1,
      "server_name": "example",
      "addresses": [
        "example"
      ],
      "direct_uri": "example",
      "ca_pem": "example"
    },
    "priority_color": "red",
    "preview_id": 1,
    "preview": {
      "id": 1,
      "status": "complete",
      "download_uri": "https://mysite.files.com/...",
      "type": "image",
      "size": "large"
    }
  }
]