API object type

file

A file object contains information about a file shared with a workspace.

{
    "id": "F0S43PZDF",
    "created": 1531763342,
    "timestamp": 1531763342,
    "name": "tedair.gif",
    "title": "tedair.gif",
    "mimetype": "image/gif",
    "filetype": "gif",
    "pretty_type": "GIF",
    "user": "U061F7AUR",
    "editable": false,
    "size": 137531,
    "mode": "hosted",
    "is_external": false,
    "external_type": "",
    "is_public": true,
    "public_url_shared": false,
    "display_as_bot": false,
    "username": "",
    "url_private": "https://.../tedair.gif",
    "url_private_download": "https://.../tedair.gif",
    "thumb_64": "https://.../tedair_64.png",
    "thumb_80": "https://.../tedair_80.png",
    "thumb_360": "https://.../tedair_360.png",
    "thumb_360_w": 176,
    "thumb_360_h": 226,
    "thumb_160": "https://.../tedair_=_160.png",
    "thumb_360_gif": "https://.../tedair_360.gif",
    "image_exif_rotation": 1,
    "original_w": 176,
    "original_h": 226,
    "deanimate_gif": "https://.../tedair_deanimate_gif.png",
    "pjpeg": "https://.../tedair_pjpeg.jpg",
    "permalink": "https://.../tedair.gif",
    "permalink_public": "https://.../...",
    "comments_count": 0,
    "is_starred": false,
    "shares": {
        "public": {
            "C0T8SE4AU": [
                {
                    "reply_users": [
                        "U061F7AUR"
                    ],
                    "reply_users_count": 1,
                    "reply_count": 1,
                    "ts": "1531763348.000001",
                    "thread_ts": "1531763273.000015",
                    "latest_reply": "1531763348.000001",
                    "channel_name": "file-under",
                    "team_id": "T061EG9R6"
                }
            ]
        }
    },
    "channels": [
        "C0T8SE4AU"
    ],
    "groups": [],
    "ims": [],
    "has_rich_preview": false
}

Properties

Field	Type	Description
`id`	string	The ID of the file object.
`created`	Unix timestamp	A Unix timestamp representing when the file was created.
`timestamp`	Unix timestamp	A deprecated property that is provided only for backwards compatibility with older clients.
`name`	string	Name of the file; may be `null` for unnamed files.
`title`	string	Title of the file.
`mimetype`	string	The file's mimetype.
`filetype`	string	The file's type. Note the `mimetype` and `filetype` properties do not have a 1-to-1 mapping, as multiple different files types ('html', 'js',etc.) share the same mime type.
`pretty_type`	string	A human-readable version of the type.
`user`	string	The ID of the user who created the object.
`editable`	boolean	Indicates that files are stored in editable mode.
`size`	integer	The filesize in bytes. Snippets are limited to a maximum file size of 1 megabyte.
`mode`	string	One of the following: `hosted`, `external`, `snippet` or `post`.
`is_external`	boolean	Indicates whether the master copy of a file is stored within the system or not. If the file `is_external`, then the `url` property will point to the externally-hosted master file.
`external_type`	string	Indicates what kind of external file it is, e.g. `dropbox` or `gdoc`.
`is_public`	boolean	`true` if the file is public.
`public_url_shared`	boolean	`true` if the file's public URL has been shared.
`updated`	Unix timestamp	For Post filetypes only; a Unix timestamp of when the Post was last edited.
`channels`	array	Contains the IDs of any channels into which the file is currently shared.
`groups`	array	Contains the IDs of any private groups into which the file is currently shared. Groups are only returned if the caller is a member of that group.
`ims`	array	Contains the IDs of any IM channels into which the file is currently shared. IMs are only returned if the caller is a member of that IM channel.
`num_stars`	integer	Contains the number of users who have starred this file. It is not present if no users have starred it.
`is_starred`	boolean	`true` if the calling user has starred the file, else it is omitted.
`pinned_to`	array	Contains the IDs of any channels to which the file is currently pinned.
`reactions`	object	Contains any reactions that have been added to the file and gives information about the type of reaction, the total number of users who added that reaction and a (possibly incomplete) list of users who have added that reaction to the file. The users array in the `reactions` property might not always contain all users that have reacted (we limit it to X users, and X might change), however, `count` will always represent the count of all users who made that reaction (i.e. it may be greater than `users.length`). If the authenticated user has a given reaction then they are guaranteed to appear in the `users` array, regardless of whether `count` is greater than `users.length` or not.
`initial_comment`	string	A comment from the file uploader, and will only be set when the uploader commented on the file at the time of upload. Clients can use this to display the comment with the file when announcing new file uploads. Use `comments_count` to determine how many comments are attached to a file.

Depending on the file's type, you may encounter different fields relevant to that type. For instance, you may encounter fields such as image_exif_rotation, original_w, and original_h for images but not find those fields for HTML documents.

Lists related properties

When the file is a list, meaning filetype has value list, there will be additional fields in the response for this API.

{
    ...
    "filetype": "list",
    "list_metadata": {
        "icon": "",
        "description": "",
        "description_blocks": [
            {
                "type": "rich_text",
                "block_id": "k\/5jH",
                "elements": [
                    {
                        "type": "rich_text_section",
                        "elements": [
                            {
                                "type": "text",
                                "text": "My list description"
                            }
                        ]
                    }
                ]
            }
        ],
        "creation_source": {
            "type": "blank"
        },
        "is_trial": false,
        "schema": [
            {
                "id": "Col0181CWE8KC",
                "name": "Task",
                "key": "name",
                "type": "text",
                "is_primary_column": true,
                "options": {
                    "format": "text"
                }
            },
            {
                "id": "Col00",
                "name": "Completed",
                "key": "todo_completed",
                "type": "todo_completed",
                "is_primary_column": false
            },
            {
                "id": "Col01",
                "name": "Assignee",
                "key": "todo_assignee",
                "type": "todo_assignee",
                "is_primary_column": false
            },
            {
                "id": "Col02",
                "name": "Due Date",
                "key": "todo_due_date",
                "type": "todo_due_date",
                "is_primary_column": false
            },
            {
                "id": "Col01831YFLG3",
                "name": "Notes",
                "key": "Col01831YFLFM",
                "type": "text",
                "is_primary_column": false,
                "options": {
                    "format": "text"
                }
            }
        ],
        "subtask_schema": [
            {
                "id": "Col0181CWE8KC",
                "name": "Task",
                "key": "name",
                "type": "text",
                "is_primary_column": true,
                "options": {
                    "format": "text"
                }
            },
            {
                "id": "Col00",
                "name": "Completed",
                "key": "todo_completed",
                "type": "todo_completed",
                "is_primary_column": false
            },
            {
                "id": "Col01",
                "name": "Assignee",
                "key": "todo_assignee",
                "type": "todo_assignee",
                "is_primary_column": false,
                "options": {
                    "format": "multi_entity",
                    "default_value": null,
                    "show_member_name": true
                }
            },
            {
                "id": "Col02",
                "name": "Due Date",
                "key": "todo_due_date",
                "type": "todo_due_date",
                "is_primary_column": false
            }
        ],
        "views": [
            {
                "id": "View0181CWE8KU",
                "name": "All items",
                "type": "table",
                "is_locked": false,
                "position": "1731452687",
                "columns": [
                    {
                        "visible": true,
                        "key": "name",
                        "id": "Col0181CWE8KC",
                        "position": "5000000000"
                    },
                    {
                        "visible": true,
                        "key": "todo_completed",
                        "id": "Col00",
                        "position": "5000000001"
                    },
                    {
                        "visible": true,
                        "key": "todo_assignee",
                        "id": "Col01",
                        "position": "5000000002"
                    },
                    {
                        "visible": true,
                        "key": "todo_due_date",
                        "id": "Col02",
                        "position": "5000000003"
                    },
                    {
                        "visible": true,
                        "key": "Col01831YFLFM",
                        "id": "Col01831YFLG3",
                        "position": "5000000006"
                    }
                ],
                "date_created": 1753729952,
                "created_by": "U02178QA5BA",
                "stick_column_left": false,
                "is_all_items_view": true,
                "default_view_key": "all_items",
                "show_completed_items": true
            }
        ],
        "integrations": [],
        "todo_mode": true,
        "default_view": "View0181CWE8KU"
    },
    "list_limits": {
        "over_row_maximum": false,
        "row_count_limit": 1000,
        "row_count": 455,
        "archived_row_count": 75,
        "over_column_maximum": false,
        "column_count": 2,
        "column_count_limit": 30,
        "over_view_maximum": false,
        "view_count": 1,
        "view_count_limit": 50,
        "max_attachments_per_cell": 10
    }
}

Field	Type	Description
`list_metadata`	object	This field contains list information such as list schema, which has all columns with header names of the list. This field also has list views information (all existent views for the given list) and subtasks schema (column information for subtasks). Header name for columns will be present in `schema[].name` field, and list view names will be present in `views[].name`.
`list_limits`	object	List count of current amount of rows/items, columns, views and archived items. It also have the limits for each entity, including the maximum amount of items a list can have. Task tracking field columns (todo_completed, todo_due_date and todo_assignee type columns) don't count towards `column_count` limit.

Authentication

Authentication is required to retrieve file URLs.

The url_private property points to a URL to the file contents. Editable-mode files will also have a url_private_download parameter, which includes headers to force a browser download. Both url_private and url_private_download require an authorization header of the form:

Authorization: Bearer A_VALID_TOKEN

In this case, A_VALID_TOKEN is representative of a real OAuth token, bearing at least the files:read scope. Learn more about OAuth Scopes.

Fields providing URLs that require this form of authentication include:

url_private
url_private_download
thumb_64
thumb_80
thumb_160
thumb_360
thumb_480
thumb_720
thumb_960
thumb_1024

Please note that the url and url_download parameters have been deprecated. Please use url_private and url_private_download instead.

Thumbnails

If a thumbnail is available for the file, the URL to a 64x64 pixel will be returned as the thumb_64 prop.

The thumb_80 prop (when present) contains the URL of an 80x80 thumb. Unlike the 64px thumb, this size is guaranteed to be 80x80, even when the source image was smaller (it's padded with transparent pixels).

A variable sized thumb will be returned as thumb_360, with its longest size no bigger than 360 (although it might be smaller depending on the source size). Dimensions for this thumb are returned in thumb_360_w and thumb_360_h.

In the case where the original image was an animated gif with dimensions greater than 360 pixels, we also created an animated thumbnail and pass it as thumb_360_gif.

Depending on the original file's size, you may even find a thumb_480, thumb_720, thumb_960, or thumb_1024 property.

All thumbnails require an authorization header as described above.

Permalinks

The permalink URL points to a single page for the file containing details, comments and a download link. If the file is available to the public, a permalink_public URL points to the public file itself.

The edit_link is only present for posts and snippets and is the page at which the file can be edited.

Previews

For posts, we also include a short plain-text preview than can be shown in place of a thumbnail.

For snippets, we include a preview of the contents (a few truncated lines of plaintext), as well as a more complex syntax-highlighted preview (preview_highlight) in HTML. The total count of lines in the snippet if returned in lines, while lines_more contains a count of lines not shown in the preview.

Slack Connect files

When a file is uploaded into a Slack Connect channel, file object properties are not immediately accessible to apps listening via the Events API or RTM API. Instead, the payload will contain a file object with the key-value pair "file_access": "check_file_info" meaning that further action is required from your app in order to view an uploaded file's metadata.

    "files": [
        {
          "id": "F12345678",
          "mode": "file_access",
          "file_access": "check_file_info",
          "created": 0,
          "timestamp": 0,
          "user": ""
        }
      ]

See Slack Connect: working with channels between organizations for more details on how to handle this scenario.

File types

Possible filetype values include, but are not limited to the following:

Type	Description
`auto`	Auto Detect Type
`text`	Plain Text
`ai`	Illustrator File
`apk`	APK
`applescript`	AppleScript
`binary`	Binary
`bmp`	Bitmap
`boxnote`	BoxNote
`c`	C
`csharp`	C#
`cpp`	C++
`css`	CSS
`csv`	CSV
`clojure`	Clojure
`coffeescript`	CoffeeScript
`cfm`	ColdFusion
`d`	D
`dart`	Dart
`diff`	Diff
`doc`	Word Document
`docx`	Word document
`dockerfile`	Docker
`dotx`	Word template
`eml`	Email
`eps`	EPS
`epub`	EPUB
`erlang`	Erlang
`fla`	Flash FLA
`flv`	Flash video
`fsharp`	F#
`fortran`	Fortran
`gdoc`	GDocs Document
`gdraw`	GDocs Drawing
`gif`	GIF
`go`	Go
`gpres`	GDocs Presentation
`groovy`	Groovy
`gsheet`	GDocs Spreadsheet
`gzip`	Gzip
`html`	HTML
`handlebars`	Handlebars
`haskell`	Haskell
`haxe`	Haxe
`indd`	InDesign Document
`java`	Java
`javascript`	JavaScript
`jpg`	JPEG
`json`	JSON
`keynote`	Keynote Document
`kotlin`	Kotlin
`latex`	LaTeX/sTeX
`lisp`	Lisp
`lua`	Lua
`m4a`	MPEG 4 audio
`markdown`	Markdown (raw)
`matlab`	MATLAB
`mhtml`	MHTML
`mkv`	Matroska video
`mov`	QuickTime video
`mp3`	mp4
`mp4`	MPEG 4 video
`mpg`	MPEG video
`mumps`	MUMPS
`numbers`	Numbers Document
`nzb`	NZB
`objc`	Objective-C
`ocaml`	OCaml
`odg`	OpenDocument Drawing
`odi`	OpenDocument Image
`odp`	OpenDocument Presentation
`ods`	OpenDocument Spreadsheet
`odt`	OpenDocument Text
`ogg`	Ogg Vorbis
`ogv`	Ogg video
`pages`	Pages Document
`pascal`	Pascal
`pdf`	PDF
`perl`	Perl
`php`	PHP
`pig`	Pig
`png`	PNG
`post`	Slack Post
`powershell`	PowerShell
`ppt`	PowerPoint presentation
`pptx`	PowerPoint presentation
`psd`	Photoshop Document
`puppet`	Puppet
`python`	Python
`qtz`	Quartz Composer Composition
`r`	R
`rtf`	Rich Text File
`ruby`	Ruby
`rust`	Rust
`sql`	SQL
`sass`	Sass
`scala`	Scala
`scheme`	Scheme
`sketch`	Sketch File
`shell`	Shell
`smalltalk`	Smalltalk
`svg`	SVG
`swf`	Flash SWF
`swift`	Swift
`tar`	Tarball
`tiff`	TIFF
`tsv`	TSV
`vb`	VB.NET
`vbscript`	VBScript
`vcard`	vCard
`velocity`	Velocity
`verilog`	Verilog
`wav`	Waveform audio
`webm`	WebM
`wmv`	Windows Media Video
`xls`	Excel spreadsheet
`xlsx`	Excel spreadsheet
`xlsb`	Excel Spreadsheet (Binary, Macro Enabled)
`xlsm`	Excel Spreadsheet (Macro Enabled)
`xltx`	Excel template
`xml`	XML
`yaml`	YAML
`zip`	Zip