Files (assets)
Any file you upload to monday.com is saved as an asset, and each asset has a unique ID to identify it within an account.
As a developer working with monday.com, it is important to familiarize yourself with the assets
API so you know how to access asset data. This document will walk you through the available queries and mutations to read and modify the assets
object via the API.
Queries
Required scope: assets:read
Querying assets
will return one or a collection of assets. This method accepts various arguments and returns an array.
You can query assets
directly at the root or nest it within another query. If you want to query one or more assets by their ID, use assets
directly at the root.
You can also nest it within another query if you don't know the asset ID. Nesting assets
within an items
or updates
query allows you to query for assets as part of an item or update. Make sure to use the limit
argument when possible to lower the complexity cost of your query!
query {
boards (ids:1234567890) {
items (limit:100) {
assets {
id
url
name
}
}
}
}
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : "query { boards (ids: 1234567890) { items (limit: 100) { assets { id url name }}";
})
});
Arguments
You can use the following argument(s) to reduce the number of results returned in your assets
query.
Argument | Description |
---|---|
ids [Int]! | The specific assets to return. Please note that this argument's type is [ID!]! in API versions 2023-10 and later. |
Fields
You can use the following field(s) to specify what information your assets
query will return.
Field | Description |
---|---|
created_at Date | The asset's creation date. |
file_extension String! | The asset's extension. |
file_size Int! | The asset's size in bytes. |
id ID! | The asset's unique identifier. |
name String! | The asset's name. |
original_geometry String | The asset's original geometry. |
public_url String! | The asset's public URL (valid for 1 hour). Accessing this link will allow users without a monday.com user profile to see the file directly while the link is valid. |
uploaded_by User! | The user who uploaded the asset. Please note that this field will not return anything if the asset is a duplicate of something generated by a system. |
url String! | The asset's URL. This will only be available to users who have access to the file as part of your account. If the asset is stored on a private or shareable board, it will also need to be part of the board in question. |
url_thumbnail String | The URL to view the asset in thumbnail mode. Only available for images. |
Mutations
You can upload files to monday.com using the API. Files are saved as assets and always belong to a parent object (like an item or an update).
Files endpoint
When uploading files, you should use an alternate endpoint: https://api.monday.com/v2/file
. You can upload files up to 500 MB in size using this endpoint, whereas the normal endpoint only supports files up to 1 MB.
Making multipart requests
If you are making direct requests to the API, you have to use the multipart/form-data
content type, as described in our community. Depending on the language or library, you may need to construct the body of the multipart HTTP request manually. Check out a JavaScript example in this community post.
Add a file to an update
Required scope: updates:write
The add_file_to_update
mutation allows you to add a file to an update via the API. You can also specify what fields to query back when you run the mutation. Please note that the file will be added to the bottom of the update.
Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
add_file_to_update (update_id: 1234567890, file: YOUR_FILE) {
id
}
}
/// those are the main dependecies you'll need to have installed in this example;
const fs = require('fs');
const fetch = require('node-fetch');
/// Replace with your actual API Key
const API_KEY= "YOUR_API_KEY_HERE";
/// Notice the /file/ endpoint - only this endpoint will support variables in this type of call
const url = 'https://api.monday.com/v2/file';
/// This is your mutation query - can also be adapted to send files to file columns instead
const query = 'mutation ($file: File!) { add_file_to_update (update_id: 1234567890, file: $file) {id}}'
///This is the mapping for the API call, where you specify that a variable should be considered as the variables[file] of the request.
///This can be called "image", or simply file - as long as it matches the name of the multipart request later down the line.
var map = {"image":"variables.file"};
/// this is the path to the file you'd like to upload to monday.com
var upfile = `./300px-All_Right_Then,_Keep_Your_Secrets.jpg`;
var data = "";
const boundary = "xxxxxxxxxxxxxxx";
fs.readFile(upfile, function(err, content){
// simple catch error
if(err){
console.error(err);
}
//below, we will construct a multipart request. Take a look at the "name" within each part, as those will refer to different parts of the API call.
// construct query part
data += "--" + boundary + "\r\n";
data += "Content-Disposition: form-data; name=\"query\"; \r\n";
data += "Content-Type:application/json\r\n\r\n";
data += "\r\n" + query + "\r\n";
// construct map part
data += "--" + boundary + "\r\n";
data += "Content-Disposition: form-data; name=\"map\"; \r\n";
data += "Content-Type:application/json\r\n\r\n";
data += "\r\n" + JSON.stringify(map)+ "\r\n";
// construct file part - the name needs to be the same as passed in the map part of the request. So if your map is {"image":"variables.file"}, the name should be image.
data += "--" + boundary + "\r\n";
data += "Content-Disposition: form-data; name=\"image\"; filename=\"" + upfile + "\"\r\n";
data += "Content-Type:application/octet-stream\r\n\r\n";
var payload = Buffer.concat([
Buffer.from(data, "utf8"),
new Buffer.from(content, 'binary'),
Buffer.from("\r\n--" + boundary + "--\r\n", "utf8"),
]);
// construct request options
var options = {
method: 'post',
headers: {
"Content-Type": "multipart/form-data; boundary=" + boundary,
"Authorization" : API_KEY
},
body: payload,
};
// make request
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json));
});
Arguments
You can use the following argument(s) to specify which file to add and to what update.
Argument | Description |
---|---|
file File! | The file to upload. |
update_id Int! | The unique identifier of the update where the file will be added. You can also use a reply ID to add the file to an update's reply. Please note that this argument's type is ID! in API versions 2023-10 and later. |
Add file to the file column
Required scope: boards:write
The add_file_to_column
mutation will add a file to the file column of a specific item. You can also specify what fields to query back when you run the mutation.
Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
add_file_to_column (item_id: 1234567890, column_id: "files", file: YOUR_FILE) {
id
}
}
var fs = require('fs');
var fetch = require('node-fetch'); // requires node-fetch as dependency
// adapted from: https://gist.github.com/tanaikech/40c9284e91d209356395b43022ffc5cc
// set filename
var upfile = 'sample.png';
// set auth token and query
var API_KEY = "MY_API_KEY"
var query = 'mutation ($file: File!) { add_file_to_column (file: $file, item_id: 1234567890, column_id: "files") { id } }';
// set URL and boundary
var url = "https://api.monday.com/v2/file";
var boundary = "xxxxxxxxxx";
var data = "";
fs.readFile(upfile, function(err, content){
// simple catch error
if(err){
console.error(err);
}
// construct query part
data += "--" + boundary + "\r\n";
data += "Content-Disposition: form-data; name=\"query\"; \r\n";
data += "Content-Type:application/json\r\n\r\n";
data += "\r\n" + query + "\r\n";
// construct file part
data += "--" + boundary + "\r\n";
data += "Content-Disposition: form-data; name=\"variables[file]\"; filename=\"" + upfile + "\"\r\n";
data += "Content-Type:application/octet-stream\r\n\r\n";
var payload = Buffer.concat([
Buffer.from(data, "utf8"),
new Buffer.from(content, 'binary'),
Buffer.from("\r\n--" + boundary + "--\r\n", "utf8"),
]);
// construct request options
var options = {
method: 'post',
headers: {
"Content-Type": "multipart/form-data; boundary=" + boundary,
"Authorization" : API_KEY
},
body: payload,
};
// make request
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json));
});
Arguments
You can use the following argument(s) to specify which files to add and to what item.
Arguments | Description |
---|---|
column_id String! | The unique identifier of the column where the file will be added. |
file File! | The file to upload. |
item_id Int! | The unique identifier of the item where the file will be added. Please note that this argument's type is ID! in API versions 2023-10 and later. |
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎
Updated 3 months ago