Objects are a core component of the platform API that represent a generic item within the monday.com platform. They can represent boards, dashboards, workflows, or other specialized objects.

Queries

You can use the objects query to retrieve object data via the API.

Returns an array containing metadata about a collection of objects
Can only be queried directly at the root; can't be nested within another query

query {
  objects(
    limit: 4, 
    state: ACTIVE, 
    order_by: CREATED_AT
  ) {
    id
    name
    owners {
      id
      name
    }
  }
}

{
  "data": {
    "objects": [
      {
        "id": "OBJECT_ID_1",
        "name": "Object 1",
        "owners": [
          {
            "id": "OWNER_ID_1",
            "name": "Owner 1"
          }
        ]
      },
      {
        "id": "OBJECT_ID_2",
        "name": "Object 2",
        "owners": [
          {
            "id": "OWNER_ID_2",
            "name": "Owner 2"
          }
        ]
      },
      {
        "id": "OBJECT_ID_3",
        "name": "Object 3",
        "owners": [
          {
            "id": "OWNER_ID_3",
            "name": "Owner 3"
          }
        ]
      },
      {
        "id": "OBJECT_ID_4",
        "name": "Object 4",
        "owners": [
          {
            "id": "OWNER_ID_4",
            "name": "Owner 4"
          }
        ]
      }
    ]
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following arguments to reduce the number of results returned in your objects query.

Argument	Description	Enum Values
ids `[ID!]`	The unique identifiers of the objects to filter by.
limit `Int`	The number of objects to get. The default is 25.
object_type_unique_keys `[String!]`	The unique identifier of the object type to filter by. Query `object_types_unique_keys` to see available types.
order_by `OrderBy`	The order in which to return objects.	`CREATED_AT` `USED_AT`
privacy_kind `PrivacyKind`	The object visibility settings to filter by.	`PRIVATE` `PUBLIC`
state `ObjectState`	The object state to filter by.	`ACTIVE` `ARCHIVED` `DELETED`
workspace_ids `[ID!]`	The unique identifiers of the workspaces to filter by.

Fields

You can use the following fields to specify what information your objects query will return.

Field	Description
creator `String`	The object's creator.
description `String`	The object's description.
folder_id `String`	The unique identifier of the folder that contains the object.
id `String`	The object's unique identifier.
name `String`	The object's name.
owners `[User!]`	The object's owners.
privacy_kind `String`	The object's visibility settings.
state `String`	The object's state.
subscribers `[User!]`	The object's subscribers.
updated_at `String`	The object's last updated date.
workspace_id `String`	The unique identifier of the workspace that contains the object.

Mutations

The API allows you to create, update, and delete objects using the following mutations. These operations let you programmatically control an object's full lifecycle.

Create object

The create_object mutation creates an object via the API. You can specify which fields to return in the mutation response.

mutation {
  create_object(
    name: "New Marketing Campaign"
    privacy_kind: PUBLIC
    object_type_unique_key: "service::portal-object"
    description: "Our Q3 marketing campaign."
    folder_id: 9876543210
    owner_ids: [12345]
  ) {
    id
    name
    description
    owners {
      id
    }
  }
}

{
  "data": {
    "create_object": {
      "id": "1234567890",
      "name": "New Marketing Campaign",
      "description": "Our Q3 marketing campaign.",
      "owners": [
        {
          "id": "12345"
        }
      ]
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following arguments to define the new object's characteristics.

Argument	Description	Enum Values
description `String`	The new object's description.
folder_id `ID`	The unique identifier of the folder to create the object in.
name `String!`	The new object's name.
object_type_unique_key `String!`	The object type's unique identifier. Query `object_types_unique_keys` to see available types.
owner_ids `[ID!]`	The unique identifiers of the new object's owners.
owner_team_ids `[ID!]`	The unique identifiers of the new object's team owners.
payload `JSON`	The new object's JSON payload.
privacy_kind `PrivacyKind!`	The new object's visibility settings.	`PRIVATE` `PUBLIC`
subscriber_ids `[ID!]`	The unique identifiers of the new object's subscribers.
subscriber_team_ids `[ID!]`	The unique identifiers of the new object's team subscribers.
workspace_id `ID`	The unique identifier of the workspace to create the object in.

Update object

The update_object mutation update an object via the API. You can specify which fields to return in the mutation response.

mutation {
  update_object(
    id: "12345678",
    input: {
      description: "Our Q4 marketing campaign.",
      name: "New Marketing Campaign"
      privacy_kind: PRIVATE
    }
  ) {
    name
    description
    privacy_kind
  }
}

{
  "data": {
    "update_object": {
      "name": "New Marketing Campaign",
      "description": "Our Q4 marketing campaign.",
      "privacy_kind": "private"
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following arguments to define the updated object's characteristics.

Argument	Description	Supported Fields
id `String!`	The unique identifier of the object to update.
input `UpdateObjectInput!`	The updated object's characteristics.	description `String` name `String` privacy_kind `PrivacyKind`

Add subscribers to object

The add_subscribers_to_object mutation adds subscribers or owners to an existing object via the API. You can specify which fields to return in the mutation response.

mutation {
  add_subscribers_to_object(
    id: 12345, 
    user_ids: [1234567890, 9876543210], 
    kind: SUBSCRIBER
	) {
    subscribers {
      id
      name
    }
  }
}

{
  "data": {
    "add_subscribers_to_object": {
      "subscribers": [
        {
          "id": "1234567890",
          "name": "Owner 1"
        },
        {
          "id": "9876543210",
          "name": "Owner 2"
        },
				{
          "id": "123459876",
          "name": "Owner 3"
        }
      ]
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following arguments to specify which subscribers to add to the object.

Argument	Description	Enum Values
id `ID!`	The unique identifier of the object to add subscribers to.
kind `SubscriberKind`	The role to assign the subscribers. The default is `SUBCRIBER`.	`OWNER` (full control permissions) `SUBSCRIBER` (notification access only)

Archive object

The archive_object mutation archives an object via the API. You can specify which fields to return in the mutation response.

mutation {
  archive_object(id: 12345) {
    state
    name
  }
}

{
  "data": {
    "archive_object": {
      "state": "archived",
      "name": "Object 3"
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following argument to specify which object to archive.

Argument	Description
id `ID!`	The unique identifier of the object to archive.

Delete object

The delete_object mutation permanently deletes any object via the API. You can specify which fields to return in the mutation response.

When an object is deleted, there is a 30-day grace period to reverse the action. After those initial 30 days, the object will be permanently deleted and can't be retrieved.

mutation {
  delete_object(id: 12345) {
    state
    name
  }
}

{
  "data": {
    "delete_object": {
      "state": "deleted",
      "name": "Object 4"
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following argument to specify which object to delete.

Argument	Description
id `ID!`	The unique identifier of the object to delete.