Looking for API documentation?

This article discusses the monday.api JavaScript method. You can find our API documentation here!

You can use the monday.api software development kit (SDK) method to query the GraphQL API seamlessly on behalf of the connected user or by using an API token. Scopes will be based on the permissions of the logged-in user and the scopes you have configured in your app.

Our GraphQL API exposes methods to get board data, create items, notify people, and much more. Check out our API documentation for more information.


  • query: A GraphQL query, can be either a query (retrieval operation) or a mutation (creation/update/deletion operation). Placeholders may be used, which will be substituted by the variables object passed within the options.
  • options:
apiVersionThe API version to send the request toNoIf not included, the request will use the current stable version.
tokenAccess token for the APIOnly on serverIf not set, it will use the credentials of the current user (client only).
variablesAn object containing GraphQL query variablesNo

Instead of passing the API token to the api() method on each request, you can set the API token once using:



A Promise that will be resolved to the API response.

If there was an unhandled GraphQL error in the API, a Promise will be rejected with an Error. In case of handled errors from GraphQL API (response with the 200 status), a Promise will be resolved with the API response.

You can check the list of GraphQL API errors here.


Setting the API version

monday.api('query { account { id } }', {
  apiVersion: '2023-10'
.then(res => { ... })

Client-side query that fetches the ID and name of users within the account that the connected user can view

monday.api(`query { users { id, name } }`).then(res => {
  /* { data: { users: [{id: 12312, name: "Bart Simpson"}, {id: 423423, name: "Homer Simpson"}] } } */

Server-side query that fetches all the names of users in the account

monday.api('query { users { name } }').then(res => {...})

Mutation that sends a notification to user user_id, which will take the user to item_id after clicking

  mutation {
      text: "I've got a notification for you!",
      user_id: ${user_id},
      target_id: ${item_id},
      target_type: Project,
      internal: true
    ) { 


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