Files

Object

Use live API calls for an example of the object.

Fields

Field Type Description
audio_info object Included if kind: audio.
Field Type Description
duration integer Length of audio in seconds.
bitrate integer Bitrate in kbps.
created_at string The time at which the file was created in ISO 8601 format.
file_token string A token to modify the file. Only included on creation, if included in the query string, or if the Files scope gives you access to the file.
file_token_read string A token to access the file. Only included 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 Post and User with the same ID; no relation is implied.
image_info object Included 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, image, and other. audio is currently limited to 52428800-byte files (32MiB). See Mime Types for explanation.
link string Direct link to the file, but with an expiration.
link_expires_at string ISO 8601 timestamp of when link will expire. After expiration, file object will need to be fetched to get a new link (GET /files/{file_id}, this also refreshes any derivative files).
link_short string A redirect link to the file. Only included if is_public.
mime_type string Optional. Mime encoding of the file. See Mime Types for details.
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.
sha256 string sha256 checksum of file
size integer Size of the file in bytes.
source object An embedded object of the client that created the file.
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.
upload_parameters object Only included on creation of a file placeholder.
Field Type Description
method string e.g., post
url string URL to upload the file to
derivative_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
link string Direct link to the file, but with an expiration.
link_expires_at string ISO 8601 timestamp of when link will expire. After expiration, GET /files/{file_id} of the derived file will refresh these as well.
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.
image_info object Included if kind: image.
Field Type Description
height integer Height of the image.
width integer Width of the image.
user object This is an embedded User object. In certain cases, this key may be omitted.

General File Parameters

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

General Parameters

Name Type Description
include_incomplete integer (0 or 1) Include incomplete files. Only applicable to the user's file stream. Defaults to true.
include_private integer (0 or 1) Include private files. Only applicable to the user's file stream. Defaults to true.
mime_types list Comma-separated list of mime types to retrieve. Only applicable to the user's file stream.
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.
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.
include_raw integer (0 or 1) Include raw on all objects. Defaults to false.
include_file_raw integer (0 or 1) Include raw on all file objects. Defaults to 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
WAV audio/wave audio/wav, audio/x-wav, audio/x-pn-wav
FLAC audio/flac audio/x-flac

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 -