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

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.

👍

Pro tip

Make sure to use the limit argument when possible to lower the complexity cost of your query!

{
  boards (ids:1234567890) {
    items_page (limit:100) {
      items {
        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_page (limit: 100) { items { assets { id url name } } } } }";
   })
  });

Arguments

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

Fields

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

Mutations

You can upload JPEG, Word/Doc, PDF, XLSX, GIF, MP4, CSV, SVG, TXT, and AI 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.

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)

Arguments

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

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'

Arguments

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

📘

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! 😎