Files
The Files API has methods for managing files.
Create file
Creates a new file in the specified Files app.
Path parameters
app
string
requiredApp identifier (
id
oruid
)
Body parameters
blob_id
integer
requiredId of blob containing content and metadata for the file.
name
string
File name. When not specified the file will get the name of the underlying blob.
metadata
object
Additional metadata properties, e.g.
{ "color": "blue", "size": "XL" }
.
tags
array of strings
A list of tags to associate with the file.
replace
boolean
true
to force an existing file with the same name to be overwritten (otherwise a409 Conflict
response will be produced).
Example request
Response codes
200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Validation Failed
Response schema
Get file
Get file metadata.
Path parameters
id
integer
requiredFile id
Query parameters
trashed
boolean
true
to return file even if trashed.
Example request
Response codes
200 OK
401 Unauthorized
404 Not Found
Response schema
Get file revision
Get file revision.
Path parameters
id
integer
requiredFile id.
rev
integer
requiredRevision number.
Example request
Response codes
200 OK
401 Unauthorized
404 Not Found
Response schema
List file revisions
List revision history of a file.
Path parameters
id
integer
requiredFile id.
Example request
Response codes
200 OK
401 Unauthorized
404 Not Found
Response schema
Update file
Update file metadata.
Path parameters
id
integer
requiredId of file.
Body parameters
blob_id
integer
Id of blob containing content and metadata for the file.
name
string
The file name.
metadata
object
Additional metadata properties, e.g.
{ "color": "blue", "size": "XL" }
.
tags
array of strings
A list of tags to associate with the file.
backup
boolean
true
to add previous version to version history, otherwisefalse
(default).
Example request
Response codes
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Failed
Response schema
List files
List files.
Query parameters
around
integer
A file id. Used to find results "around" a specific file.
q
string
A string used to find matching items by name, e.g.
q=test
.
tag
string
List items with the specified tag.
trashed
boolean
Indicates whether trashed items should be listed (default is
false
). Specifynull
to list both trashed and non-trashed items.
order_by
string
Specifies the sort order and direction for the listing, e.g.
order_by=id
ororder_by=id+desc
.
skip
integer
The number of items to skip. Used together with
take
to return a specific range of items (for pagination).
take
integer
Maximum number of items to return in the listing. Should be a value between
1
and100
. Default is25
.
count_only
boolean
true
to count the number of matching items instead of listing them; when specified the response will only contain thecount
property.
Example request
Response codes
200 OK
401 Unauthorized
Response schema
List app files
List files in the specified Files app.
Path parameters
app
string
requiredApp identifier (
id
oruid
)
Query parameters
around
integer
A file id. Used to find results "around" a specific file.
q
string
A string used to find matching items by name, e.g.
q=test
.
tag
string
List items with the specified tag.
trashed
boolean
Indicates whether trashed items should be listed (default is
false
). Specifynull
to list both trashed and non-trashed items.
order_by
string
Specifies the sort order and direction for the listing, e.g.
order_by=id
ororder_by=id+desc
.
skip
integer
The number of items to skip. Used together with
take
to return a specific range of items (for pagination).
take
integer
Maximum number of items to return in the listing. Should be a value between
1
and100
. Default is25
.
count_only
boolean
true
to count the number of matching items instead of listing them; when specified the response will only contain thecount
property.
Example request
Response codes
200 OK
401 Unauthorized
404 Not Found
Response schema
List post attachments
List files attached to the specified post.
Path parameters
id
integer
requiredPost id.
Query parameters
around
integer
A file id. Used to find results "around" a specific file.
q
string
A string used to find matching items by name, e.g.
q=test
.
tag
string
List items with the specified tag.
trashed
boolean
Indicates whether trashed items should be listed (default is
false
). Specifynull
to list both trashed and non-trashed items.
order_by
string
Specifies the sort order and direction for the listing, e.g.
order_by=id
ororder_by=id+desc
.
skip
integer
The number of items to skip. Used together with
take
to return a specific range of items (for pagination).
take
integer
Maximum number of items to return in the listing. Should be a value between
1
and100
. Default is25
.
count_only
boolean
true
to count the number of matching items instead of listing them; when specified the response will only contain thecount
property.
Example request
Response codes
200 OK
401 Unauthorized
404 Not Found
Response schema
List comment attachments
List files attached to the specified comment.
Path parameters
id
integer
requiredComment id.
Query parameters
around
integer
A file id. Used to find results "around" a specific file.
q
string
A string used to find matching items by name, e.g.
q=test
.
tag
string
List items with the specified tag.
trashed
boolean
Indicates whether trashed items should be listed (default is
false
). Specifynull
to list both trashed and non-trashed items.
order_by
string
Specifies the sort order and direction for the listing, e.g.
order_by=id
ororder_by=id+desc
.
skip
integer
The number of items to skip. Used together with
take
to return a specific range of items (for pagination).
take
integer
Maximum number of items to return in the listing. Should be a value between
1
and100
. Default is25
.
count_only
boolean
true
to count the number of matching items instead of listing them; when specified the response will only contain thecount
property.
Example request
Response codes
200 OK
401 Unauthorized
404 Not Found
Response schema
List message attachments
List files attached to the specified message.
Path parameters
id
integer
requiredMessage id.
Query parameters
around
integer
A file id. Used to find results "around" a specific file.
q
string
A string used to find matching items by name, e.g.
q=test
.
tag
string
List items with the specified tag.
trashed
boolean
Indicates whether trashed items should be listed (default is
false
). Specifynull
to list both trashed and non-trashed items.
order_by
string
Specifies the sort order and direction for the listing, e.g.
order_by=id
ororder_by=id+desc
.
skip
integer
The number of items to skip. Used together with
take
to return a specific range of items (for pagination).
take
integer
Maximum number of items to return in the listing. Should be a value between
1
and100
. Default is25
.
count_only
boolean
true
to count the number of matching items instead of listing them; when specified the response will only contain thecount
property.
Example request
Response codes
200 OK
401 Unauthorized
404 Not Found
Response schema
Trash file
Move a file to the trash.
Path parameters
id
integer
requiredId of the file to trash.
Example request
Response codes
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Restore file
Restore a file from the trash.
Path parameters
id
integer
requiredId of the file to restore.
Example request
Response codes
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Restore file version
Restore a previous revision of a file to be the current. This will create a new revision with the contents of the previous revision, but preserves all existing revisions.
Path parameters
id
integer
requiredFile id.
rev
integer
requiredRevision number.
Example request
Response codes
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Delete file
Delete a file.
Path parameters
id
integer
requiredId of the file.
Example request
Response codes
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Delete file revision
Delete file revision.
Path parameters
id
integer
requiredFile id.
rev
integer
requiredFile revision.
Example request
Response codes
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found