API Reference
Apps DocsCommunityNeed Help?

Assets (files)

Learn how to read, add, and upload assets using the monday.com platform API

Files that you upload to monday.com are 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

  • Returns an array containing metadata about one or a collection of assets
  • Can be queried directly at the root using the ids argument or nested nested within an items or updates query
{
  boards (ids:1234567890) {
    items_page (limit:100) {
      items {
        assets {
          id
          url
          name
        }
      }
    }
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `query ($boardId: [ID!]) { boards (ids: $boardId) { items_page (limit: 100) { items { assets { id url name } } } } }`;
const variables = {
  boardId: 12345,
};
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following argument(s) to reduce the number of results returned in your assets query.

ArgumentDescription
ids [ID!]!The asset's unique identifiers.

Fields

You can use the following field(s) to specify what information your assets query will return.

FieldDescription
created_at DateThe 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 StringThe 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 StringThe URL to view the asset in thumbnail mode. Only available for images.

Mutations

Using the API, you can upload JPEG, Word/Doc, PDF, XLSX, GIF, MP4, CSV, SVG, TXT, and AI files to monday.com. Files are saved as assets and always belong to a parent object (like an item or an update).

👍

Files endpoint

Using the following endpoint, you can upload files up to 500 MB in size via the API: https://api.monday.com/v2/file.

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. 

mutation {
  add_file_to_update (update_id: 1234567890, file: YOUR_FILE) {
    id
  }
}

import requests

apiKey = "YOUR_TOKEN_HERE"
headers = {"Authorization" : apiKey, 'API-version':'2024-04'}
url = "https://api.monday.com/v2/file"
payload = {'query': 'mutation ($file: File!) { add_file_to_update (file: $file, update_id: 1234567890) { id } }',
	'map': '{"image":"variables.file"}'
 }
files=[
  ('image',('file',open('/path/to/my/file.svg','rb'),'application/octet-stream'))
]


response = requests.post(url, headers=headers, data=payload, files=files)

import axios from 'axios';
import fs from 'fs';
import FormData from "form-data";

let data = new FormData();
data.append('query', 'mutation ($file: File!, $updateId: ID!) { add_file_to_update (file: $file, update_id: $updateId) { id } }');
data.append('map', '{"image":"variables.file", "update": "variables.updateId"}');
data.append('image', fs.createReadStream('/local/path/to/file.png'));
data.append('update', '12345');

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.monday.com/v2/file',
  headers: { 
    'Authorization': myToken, 
    ...data.getHeaders()
  },
  data : data
};

const response = await axios.request(config)

Arguments

You can use the following argument(s) to specify which file to add and to what update.

ArgumentDescription
file File!The file to upload.
update_id ID!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.

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.

mutation {
  add_file_to_column(
    item_id: 1234567890, 
    column_id: "files", 
    file: YOUR_FILE
	) {
   	id
  }
}

import requests

apiKey = "YOUR_TOKEN_HERE"
headers = {"Authorization" : apiKey, 'API-version':'2024-04'}
url = "https://api.monday.com/v2/file"
payload = {
    'query': 'mutation add_file($file: File!) {add_file_to_column (item_id: 6530743418, column_id:"files__1" file: $file) {id}}',
    'map': '{"image":"variables.file"}'
    }
files=[
  ('image',('file',open('/path/to/my/file.svg','rb'),'application/octet-stream'))
]


response = requests.post(url, headers=headers, data=payload, files=files)

curl --location 'https://api.monday.com/v2/file' \                          
--header 'API-Version: 2024-01' \
--header 'Authorization: thisisasecret' \
--form 'query="mutation($item_id: ID!, $column_id: String!, $file: File!) { add_file_to_column(item_id: $item_id, column_id: $column_id, file: $file) { id } }"' \
--form 'variables="{\"item_id\": 123456, \"column_id\": \"files\"}"' \
--form 'map="{\"file\":\"variables.file\"}"' \
--form 'file=@/Users/me/Pictures/MyCat.png'

import axios from 'axios';
import fs from 'fs';
import FormData from "form-data";
let data = new FormData();
data.append('query', 'mutation ($file: File!) { add_file_to_column (item_id: 9393173469, column_id: "file_mksrqze", file: $file) { id } }');
data.append('map', '{"image":"variables.file"}');
data.append('image', fs.createReadStream('/local/path/to/file.png'));

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.monday.com/v2/file',
  headers: { 
    'Authorization': myToken, 
    ...data.getHeaders()
  },
  data : data
};

const response = await axios.request(config)

Arguments

You can use the following argument(s) to specify which files to add and to what item.

ArgumentsDescription
column_id String!The unique identifier of the column where the file will be added.
file File!The file to upload.
item_id ID!The unique identifier of the item where the file will be added.