Learn how to read, add, and upload assets using the monday.com platform API
Files uploaded to monday.com are saved as assets, and each asset has a unique ID that identifies it within an account.
Queries
You can retrieve file data via the API through the assets
query.
- 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 within anitems
orupdates
query
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 to reduce the number of results returned in your assets
query.
Argument | Description |
---|---|
ids [ID!]! | The asset's unique identifiers. |
Fields
You can use the following fields 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. 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
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 file to update
Required scope: updates:write
The add_file_to_update
mutation adds a file to the bottom of an update via the API. You can specify which fields to return in the mutation response.
mutation {
add_file_to_update (update_id: 1234567890, file: YOUR_FILE) {
id
}
}
Arguments
You can use the following arguments to specify which file to add and to what update.
Argument | Description |
---|---|
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 column
Required scope: boards:write
The add_file_to_column
mutation adds a file to the file column of a specific item via the API. You can specify which fields to return in the mutation response.
mutation {
add_file_to_column(
item_id: 1234567890,
column_id: "files",
file: YOUR_FILE
) {
id
}
}
Arguments
You can use the following arguments 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 ID! | The unique identifier of the item where the file will be added. |