Any file you upload to monday.com is saved as an asset. Every asset has an ID that is used to identify it in an account.

You can query for assets by their IDs or get them through the Updates or Items queries.

👍

TIP

Want to learn more about how monday.com manages files in general? Check out this article.

Files Queries

Required scope: assets:read

If you want to query one or more assets by their ID, you can use the assets field as the root of your query, like this:

query {
    assets (ids: [1,2,3]) {
        id
        name
        url
    }
}
fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : "query { assets (ids: [1,2,3]) { id name url }}";
   })
  });
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--header 'Cookie: __cfduid=d4512e647bd3dd90706f5673d6041f7c51618840981' \
--data-raw '{"query": "query { assets (ids: [1,2,3]) { id name url }}"}'

Querying assets as part of Items or Updates

You can get data from them when pulling data for a specific update or item. This is helpful if you do not know the ID of the asset you need to query.

The assets field is also supported in the Items or Updates field. If you do not know the ID of the asset you need to query, you can also query for assets as part of an Item or an Update. You will find a couple of examples below to illustrate this.

In order to lower the complexity cost of those queries, use limit where applicable!

query {
  boards (ids:1181887391) {
    items (limit:100) {
      assets {
        id
        url
        name
      }
    }
  }
}
query {
  updates (limit:100) {
    assets {
      id
      name
      url
    }
  }
}

Arguments

Querying files returns one or a collection of assets. Assets can receive the following arguments:

Field

Arguments

assets [Asset]
Get a collection of assets by IDs.

ids ![Int]
Identifiers of the assets/files you want to get.

Fields

Files are saved as assets in monday.com. Each asset contains the following fields:

Field

Description

created_at Date

The file's creation date.

file_extension !String

The file's extension.

file_size !Int

The file's size in bytes.

id !ID

The file's identifier.

name !String

The file name.

public_url !String

Public URL to the asset, which will be 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 file.

url !String

The URL to view the asset. This URL will only be available to users who would have access to the file, as part of your account. In case the file is stored on a Private or Shareable board, they will also need to be part of the board in question.

url_thumbnail String

URL to view the asset in thumbnail mode. Only available for images.

Files Mutations

You can upload files to monday.com using the API. Files are saved as "assets" and always belong to a parent object, which would be 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. The normal endpoint only supports files up to 1MB.

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 this post on our community.

Depending on the language or library, you may need to construct the body of the multipart HTTP request manually. You can find a JavaScript example in this community post.

Add a file to an update

Required scope: updates:write

This API call will add a file to an existing update. The file will be added to the bottom of the update.

mutation {
    add_file_to_update (update_id: 17, $file: 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= "YourSuperSecretApiKey";

/// 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 add_file($file: File!, $updateId: Int!) {add_file_to_update(update_id: $updateId, file: $file) {id}}'

/// These are the variables you are sending. Can be adapted to a call that would add the file to a file oclumn instead;
var vars = {"updateId":967485603};

///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 variables part
    data += "--" + boundary + "\r\n";
    data += "Content-Disposition: form-data; name=\"variables\"; \r\n";
    data += "Content-Type:application/json \r\n\r\n";
    data += "\r\n" + JSON.stringify(vars)  + "\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));
});
curl --location --request POST 'https://api.monday.com/v2/file' \
--header 'Authorization: yourSuperSecretApiKey' \
--form 'query="mutation add_file($file: File!, $update_id: Int!) {add_file_to_update(update_id: $update_id, file: $file) {id}}"' \
--form 'variables="{\"update_id\":920768626}"' \
--form 'map="{\"image\":\"variables.file\"}"' \
--form '[email protected]"path to your file/in local memory/cool picture.jpg'

This mutation includes the following arguments:

Argument

Description

update_id !Int

The update ID where the file will be added at the bottom of the update.
You can also use a reply ID to add the file to an update's reply.

file !File

The file to upload.

Add a file to the File column

Required scope: boards:write

This mutation call will add a File to the File column of a specific item. Here's an example query:

mutation {
    add_file_to_column (item_id: 143, column_id: 'files_03', $file: 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= "YourSuperSecretApiKey";

/// 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 add_file($file: File!, $updateId: Int!) {add_file_to_update(update_id: $updateId, file: $file) {id}}'

/// These are the variables you are sending. Can be adapted to a call that would add the file to a file oclumn instead;
var vars = {"item_id":1104589438, "column_id": "files"};

///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 variables part
    data += "--" + boundary + "\r\n";
    data += "Content-Disposition: form-data; name=\"variables\"; \r\n";
    data += "Content-Type:application/json \r\n\r\n";
    data += "\r\n" + JSON.stringify(vars)  + "\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));
});
curl --location --request POST 'https://api.monday.com/v2/file' \
--header 'Authorization: YourSuperSecretAPIKey' \
--form 'query="mutation add_file($file: File!, $item_id: Int!, $column_id: String!) {add_file_to_column (item_id: $item_id, column_id: $column_id, file: $file) {id}}"' \
--form 'variables="{\"item_id\":1104589438, \"column_id\": \"files\"}"' \
--form 'map="{\"image\":\"variables.file\"}"' \
--form '[email protected]"/Users/alexsavchuk/Downloads/300px-All_Right_Then,_Keep_Your_Secrets.jpg"'

This mutation will accept the following arguments:

Arguments

Description

item_id !Int

The item ID where the file will be added.

column_id !String

The column where the file will be added.

file !File

The file to upload.


Did this page help you?