Files

File Fields

Field Type Description
attached_to object Other objects that this file is embedded in as a raw object.

Only set if the file has been attached to another object.
Does not currently support files on channels, other files, or users.

Field Type Description
messages list of strings Sampled list of message IDs it is attached to.

Only set if attached to messages.
polls list of strings Sampled list of poll IDs it is attached to.

Only set if attached to polls.
posts list of strings Sampled list of post IDs it is attached to.

Only set if attached to posts.
audio_info object Audio properties.

Only set if kind: audio.

Field Type Description
duration integer Length of audio in seconds.
duration_string string Length of audio in hour:minute:second format. Not always included.
bitrate integer Bitrate in kbps.
created_at string The time at which the file was created in ISO 8601 format; YYYY-MM-DDTHH:MM:SSZ.
derived_files object Up to 10 derivative files. The keys can be anything, though keys starting with core_ are reserved. Reserved keys are allowed if they match specified parameters. For example:
Field Type Description
core_image_200s object
Field Type Description
audio_info object Audio properties.

Only set if kind: audio.

Field Type Description
duration integer Length of audio in seconds.
duration_string string Length of audio in hour:minute:second format. Not always included.
bitrate integer Bitrate in kbps.
image_info object Included if kind: image.
Field Type Description
height integer Height of the image.
width integer Width of the image.
mime_type string The mime-encoding of the file.
name string A readable name of the file. Can be used descriptively or not. Up to 255 ASCII characters.
sha256 string sha256 checksum of file.
size integer Size of the file in bytes.
url string Direct link to the file, but with an expiration.
url_expires_at string ISO 8601 timestamp of when url will expire; YYYY-MM-DDTHH:MM:SSZ. After expiration, GET /files/{file_id} of the derived file will refresh these as well.
video_info object Video properties.

Only set if kind: video.

Field Type Description
duration integer Length of video in seconds.
duration_string string Length of video in hour:minute:second format. Not always included.
bitrate integer Bitrate in kbps.
height integer Height of the video.
width integer Width of the video.
file_token string A token to allow you to modify the file.

Only set on POST creation response, if included in the query string, or if the Files scope gives you access to the file.
file_token_read string A token to allow you to access the file.

Only set if is_public or if it is included in the query string.
id string Primary identifier for a file. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed. This id space is unique to file objects. There can be a File and User with the same ID; no relation is implied.
image_info object Image properties.

Only set if kind: image.

Field Type Description
height integer Height of the image.
width integer Width of the image.
is_complete boolean Whether file is a placeholder, or the contents have been uploaded.
is_public boolean Whether file is public or private. If private, it still may be attached to a public object, such as a post.
kind string Valid options are audio, video, image, and other. audio is currently limited to 52428800-byte files (32MiB). See Mime Types for explanation.
mime_type string Mime encoding of the file. See Mime Types for details.

Only set if file is complete.
name string A readable name of the file. Can be used descriptively or not. Up to 256 Unicode characters. Be sure to escape if necessary.
raw object The raw items attached to this object.

Only set if query parameter specified.

Field Type Description
{type name} list of objects A list of objects of this type.
sha256 string sha256 checksum of file.

Only set if file is complete.
size integer Size of the file in bytes.

Only set if file is complete.
source object An embedded object of the client that created the file.
total_size integer Size of the file plus any derivative files, in bytes.

Only set if file is complete.
type string The type of file. Generally uses a reversed domain name to identify the intended purpose. Non-core file types (io.pnut.core.*) are not authenticated by the server; clients should not assume other clients created their file types the same way.
user object This is an embedded User object.

In certain cases, this key may be omitted.
user_id string Primary identifier for the user who created the file.

Only set if the user above is omitted.
url string Direct link to the file, but with an expiration.

Only set if file is complete.
url_expires_at string ISO 8601 timestamp of when url will expire; YYYY-MM-DDTHH:MM:SSZ. After expiration, file object will need to be fetched to get a new link (GET /files/{file_id}, this also refreshes any derivative files).

Only set if file is complete.
url_short string A redirect link to the file.

Only set if is_public and file is complete.
upload_parameters object

Only set on creation of a file placeholder.

Field Type Description
method string e.g., post
url string URL to upload the file to
video_info object Video properties.

Only set if kind: video.

Field Type Description
duration integer Length of video in seconds.
duration_string string Length of video in hour:minute:second format. Not always included.
bitrate integer Bitrate in kbps.
height integer Height of the video.
width integer Width of the video.

General File Parameters

Any endpoint that returns file objects can be subject to these parameters.

General Parameters

Name Type Description Default
include_incomplete integer (0 or 1) Include incomplete files. Only applicable to the user's file stream. true
include_private integer (0 or 1) Include private files. Only applicable to the user's file stream. true
mime_types list Comma-separated list of mime types to retrieve. Only applicable to the user's file stream. all
file_types string Comma-separated list of file types to retrieve. Only applicable to the user's file stream. If not included, will return any files the app is authorized to view. all
exclude_file_types string Comma-separated list of file types not to retrieve. Only applicable to the user's file stream. Ignored if file_types set. none
include_raw integer (0 or 1) Include raw on all objects. false
include_file_raw integer (0 or 1) Include raw on all file objects. false

Mime Types

kind and mime_type must be coordinated.

Both are optional when uploading a file in one step.

If creating a file placeholder and uploading later, kind is required on creation, and mime_type is optional on file upload.

  • If you specify both, it will return an error if they do not match.
  • If you do not specify either, the API will interpret mime_type and assign kind based on what it finds.
  • If you only specify kind, the API will interpret mime_type and return an error if they do not match.
  • If you only specify mime_type, the API will assign kind based on mime_type.

Multiple mime types are accepted for some file types, but they will be normalized and recorded as a single mime type listed in the charts below.

File Encoding

If the included mime_type matches any of the following, its text encoding will attempt to be detected by the server (i.e., for UTF-8 encoding):

  • text/{anything}
  • application/msword
  • application/vnd.oasis.opendocument.text
  • application/rtf
  • application/xml
  • application/json
  • application/javascript

Audio

Files with kind: audio must have the following mime_type:

File Type mime_type Also accepted
MP3 audio/mpeg audio/mp3
MP4 audio/mp4 audio/m4a, audio/x-m4a
WAVE audio/wave audio/wav, audio/x-wav, audio/x-pn-wav
FLAC audio/flac audio/x-flac

Video

Files with kind: video must have the following mime_type:

File Type mime_type Also accepted
MP4 video/mpeg video/quicktime, video/m4v, video/x-m4v, video/mp4
WEBM video/webm -

Image

Files with kind: image must have the following mime_type:

File Type mime_type Also accepted
PNG image/png -
JPEG image/jpeg image/jpg
GIF image/gif -