🚧
Pre-release feature. The agents API is currently available only in the dev (pre-release) API version and is not yet part of any dated API version. Signatures and types can change before release.

🔬
Early preview: This API is in early preview. Fill out this form to request early access.

The monday.com agents API lets you read, create, configure, run, and connect AI agents. The types below are used by agent queries and mutations and, in most cases, are not independently queryable.

Objects

`Agent`

Returned by: agents, create_agent, create_blank_agent, update_agent, delete_agent

An AI agent on the monday.com platform.

Field	Description	Notes
id `ID!`	The unique identifier of the agent.
kind `AgentKind`	The kind of agent (personal, account-level, or external).
state `AgentState`	The current state of the agent.
profile `AgentProfile`	The agent's name, role, and avatar.
goal `String`	The goal or objective of the agent.
plan `String`	The execution plan in markdown, describing the agent's capabilities and operating principles.
agent_model `AgentModel`	The LLM model the agent uses.
skill_ids `[ID!]!`	Reference IDs of the skills attached to the agent. Resolve names with `agent_skills_catalog`.
user_prompt `String`	The original user prompt used to create the agent.
version_id `ID!`	The current configuration version of the agent.
knowledge `[AgentKnowledgeEntry!]`	Knowledge files attached to the agent. Only populated on create mutation responses.
created_at `Date`	When the agent was created. `null` on create mutation responses — use the `agents` query to fetch it.
updated_at `Date`	When the agent was last updated. `null` on create mutation responses — use the `agents` query to fetch it.

`AgentProfile`

The visual and role identity of an agent.

Field	Description	Notes
name `String`	The display name of the agent.
role `String`	The role assigned to the agent.
role_description `String`	A description of the agent's role.
avatar_url `String`	URL of the agent's avatar image.
background_color `String`	Background color for the agent card.

`AgentKnowledge`

Returned by: agent_knowledge

The full knowledge configuration of an agent.

Field	Description	Notes
resources `[AgentKnowledgeResource!]`	Boards and docs the agent has access to.
files `[AgentKnowledgeFile!]`	Files uploaded as agent knowledge.

`AgentKnowledgeResource`

A monday.com board or doc the agent has been granted access to.

Field	Description	Notes
resource_id `ID`	The ID of the board or doc.
scope_type `KnowledgeScope`	Whether this resource is a board or a doc.
permission_type `KnowledgePermission`	The permission level the agent has on this resource.

`AgentKnowledgeFile`

A file uploaded as agent knowledge.

Field	Description	Notes
id `ID`	Unique identifier of the knowledge file.
file_name `String`	Original file name.
file_type `String`	File extension (e.g. `pdf`, `docx`, `csv`).

`AgentKnowledgeEntry`

A knowledge entry attached to an agent.

Field	Description	Notes
id `ID!`	The unique identifier of the knowledge entry.
metadata `AgentKnowledgeMetadata`	File metadata for this knowledge entry.
source_type `KnowledgeSource`	The source type of this knowledge entry.
state `KnowledgeState`	The current state of this knowledge entry.
knowledge_reference_id `ID`	Reference ID for the knowledge entry.

`AgentKnowledgeMetadata`

Metadata about a knowledge file attachment.

Field	Description	Notes
file_name `String`	Original name of the uploaded file.
file_type `String`	MIME type of the file.
asset_id `ID`	Cloudinary asset ID for image files.

`AgentSkillCatalogEntry`

Returned by: agent_skills_catalog, create_agent_skill

A skill available for agents to use. Browse the catalog, then attach by id.

Field	Description	Notes
id `ID`	Stable reference ID — pass to `add_skill_to_agent` / `remove_skill_from_agent`.
name `String`	Display name of the skill.
description `String`	What the skill does.

`AgentTriggerCatalogEntry`

Returned by: agent_triggers_catalog

An available trigger type that can be attached to an agent.

Field	Description	Notes
block_reference_id `ID!`	Pass this as `block_reference_id` to `add_trigger_to_agent`.
name `String!`	Display name of the trigger.
description `String`	What the trigger does.
field_schemas `[TriggerFieldSchema!]!`	Structured value schemas for fields you populate directly in `field_values`.
required_fields `[TriggerRequiredField!]!`	Selection fields (e.g. a board picker) that must be provided in `field_values` as `{ value, label }` pairs.

`TriggerFieldSchema`

Schema description for a trigger field that accepts a structured JSON value.

Field	Description	Notes
field_key `String!`	The key to use in `field_values` when calling `add_trigger_to_agent`.
value_schema `String!`	Human-readable description of the expected JSON shape for this field.

`TriggerRequiredField`

A selection field (e.g. a board picker) required when adding a trigger.

Field	Description	Notes
field_key `String!`	The key to use in `field_values`.
depends_on `[String!]!`	Field keys that must be provided before this field — resolve them in order.
optional `Boolean!`	Whether this field can be omitted.

`AgentActiveTrigger`

Returned by: agent_active_triggers

A trigger currently attached to an agent.

Field	Description	Notes
node_id `ID!`	Stable identifier of this trigger instance — use as `node_id` when calling `remove_trigger_from_agent`.
block_reference_id `ID!`	The trigger type, matching `block_reference_id` in the catalog.
name `String!`	Display name of the trigger type.
description `String`	Description of the trigger type.
field_summary `String`	Human-readable summary of how this trigger is configured.

`ProviderResource`

Returned by: external_provider_agents

A resource (agent, environment, or vault) available on an external provider.

Field	Description	Notes
id `ID`	The unique identifier of the resource on the provider.
name `String`	The display name of the resource.

Result types

`AgentStateResult`

Returned by: activate_agent, deactivate_agent

Result of an agent state change operation.

Field	Description	Notes
success `Boolean`	Whether the operation succeeded.

`RunAgentResult`

Returned by: run_agent

Confirmation that a manual agent run was accepted and enqueued. This does not reflect the outcome of the run itself — execution happens asynchronously.

Field	Description	Notes
trigger_uuid `String`	Correlation ID for the triggered run. Use it to track or look up the execution in downstream events.

`MutationResult`

Returned by: add_trigger_to_agent, remove_trigger_from_agent, add_skill_to_agent, remove_skill_from_agent, add_agent_resource_access, update_agent_resource_access, remove_agent_resource_access

Result of a write operation that does not need to return entity data.

Field	Description	Notes
success `Boolean!`	Whether the operation succeeded.

`ConnectExternalAgentPayload`

Returned by: connect_external_agent

Payload returned after initiating an external agent connection (async operation).

Field	Description	Notes
status `String`	The connection status (e.g. `"connecting"`). The final result is delivered via Pusher.

`ConnectExternalAgentResult`

Returned by: connect_external_agent_sync

Result of a synchronous external-agent connect. agent_id is always present; signing_secret, api_token, and instructions are populated only for custom agents and are returned only once.

Field	Description	Notes
agent_id `ID`	The internal monday agent ID.
signing_secret `String`	Custom-agent only — secret used to verify callback requests. Never logged.
api_token `String`	Custom-agent only — API token for the agent to call back into monday.com. Never logged.
instructions `String`	Custom-agent only — setup instructions for the integrator. Never logged.

`UpdateCustomAgentPayload`

Returned by: update_custom_agent

Payload returned after updating a connected custom agent.

Field	Description	Notes
success `Boolean`	Whether the update succeeded.

`DisconnectExternalAgentPayload`

Returned by: disconnect_external_agent

Payload returned after disconnecting an external agent.

Field	Description	Notes
success `Boolean`	Whether the disconnection was successful.

Input types

`CreateAgentInput`

Used by: create_agent

Input for creating an AI agent from a prompt — AI generates the profile from the prompt.

Field	Description	Notes
prompt `String!`	A description of what the agent should do — used to generate the profile, goal, and plan via AI.
agent_model `String`	The LLM model the agent should use.
pending_file_ids `[ID!]`	IDs of previously uploaded pending files to attach as knowledge during creation.

`CreateBlankAgentInput`

Used by: create_blank_agent

Input for creating a blank AI agent without AI generation.

Field	Description	Notes
name `String`	The display name of the agent.
role `String`	The role of the agent.
role_description `String`	A description of the agent's role.
avatar_url `String`	URL of the agent's avatar image.
gender `String`	Influences the generated avatar and name when `name` or `avatar_url` are not provided. Accepts `male` or `female`. Defaults to random.
background_color `String`	Background color for the agent card.
user_prompt `String`	Stored as metadata on the agent. Not used for AI generation — use `create_agent` for AI generation.

`UpdateAgentInput`

Used by: update_agent

Input for updating an AI agent. All fields are optional; only provided fields are changed.

Field	Description	Notes
name `String`	The display name of the agent.
role `String`	The role of the agent.
role_description `String`	A description of the agent's role.
plan `String`	The execution plan (instructions) for the agent, in markdown.
agent_model `AgentModel`	The LLM model the agent should use.

`ConnectExternalAgentInput`

Used by: connect_external_agent

Input for connecting an external agent via BYOA (Bring Your Own Agent).

Field	Description	Notes
external_provider_type `ExternalProvider!`	The type of external provider (e.g. `CLAUDE_MANAGED_AGENT`, `CUSTOM_AGENT`).
external_agent_id `ID!`	The unique identifier of the agent on the external provider.
credential_id `ID!`	The credential ID used to authenticate with the external provider.
name `String!`	The display name for the connected agent.
environment_id `ID`	Optional environment identifier on the external provider.
vault_id `ID`	Optional vault identifier for secret management on the external provider.
callback_url `String`	Optional callback URL for agent event notifications.

`ConnectExternalAgentSyncInput`

Used by: connect_external_agent_sync

Wrapper input for the synchronous connect mutation. Currently supports custom agents only.

Field	Description	Notes
custom `ConnectCustomAgentInput`	Connect a custom agent.

`ConnectCustomAgentInput`

Used by: ConnectExternalAgentSyncInput

Connect input for a custom external agent reachable via callback URL.

Field	Description	Notes
name `String!`	The display name for the connected agent.
callback_url `String!`	The HTTPS callback URL the platform invokes for agent events.

`UpdateCustomAgentInput`

Used by: update_custom_agent

Input for updating a connected custom agent. name and callback_url are both optional and independent — only the fields you provide are changed.

Field	Description	Notes
agent_id `Int!`	The ID of the agent to update.
name `String`	New display name for the agent.
callback_url `String`	New HTTPS callback URL for event notifications. Only valid for custom agents.

Enums

`AgentKind`

The kind of AI agent.

Enum Value	Description
`PERSONAL`	A personal agent owned by a specific user.
`ACCOUNT_LEVEL`	An account-level agent available to the entire account.
`EXTERNAL`	An agent created by an external provider.

`AgentModel`

Supported LLM models for an agent.

Enum Value	Description
`CLAUDE_SONNET_4_6`	Claude Sonnet 4.6.
`CLAUDE_OPUS_4_7`	Claude Opus 4.7.
`GPT_5_2`	GPT 5.2.
`GEMINI_2_5_FLASH`	Gemini 2.5 Flash.

`AgentState`

The current state of an agent.

Enum Value	Description
`ACTIVE`	The agent is active and can be triggered and executed.
`INACTIVE`	The agent is inactive and cannot be triggered. This is the default state after creation.
`ARCHIVED`	The agent has been archived and is no longer in active use.
`DELETED`	The agent has been permanently deleted. Deleted agents are not returned by the agent queries.
`FAILED`	The agent encountered an unrecoverable error during setup.

`KnowledgeScope`

The type of monday.com resource granted to an agent.

Enum Value	Description
`BOARD`	A monday.com board.
`DOC`	A monday.com doc.

`KnowledgePermission`

The permission level the agent has on a resource.

Enum Value	Description
`READ`	The agent can read the resource.
`READ_WRITE`	The agent can read and write the resource.

`InactiveReason`

The reason an agent is inactive.

Enum Value	Description
`ACCOUNT_LEVEL_BLOCKING`	The agent was deactivated due to an account-level block.
`DEACTIVATED_BY_USER`	The agent was manually deactivated by a user.
`RUNS_RATE_LIMIT_EXCEEDED`	The agent was deactivated automatically because it exceeded the runs rate limit.

`ExternalProvider`

The type of external agent provider.

Enum Value	Description
`CLAUDE_MANAGED_AGENT`	A Claude-managed agent hosted on Anthropic infrastructure.
`CUSTOM_AGENT`	A custom agent with a user-provided callback URL.
`OPENAI`	An OpenAI assistant.

`KnowledgeSource`

The source type of a knowledge entry.

Enum Value	Description
`FILE`	Knowledge sourced from an uploaded file.

`KnowledgeState`

The state of a knowledge entry.

Enum Value	Description
`ACTIVE`	Knowledge is active and available for retrieval.
`PENDING`	Knowledge is being processed.
`DELETED`	Knowledge has been deleted.