Agent configurations

Carom’s background AI features are carried out by agents, each identified by a slug. They read incoming mail, meeting transcripts, and company websites and act on them: tagging threads, summarizing messages, proposing tasks and deal changes, and filling in organization details. An agent configuration turns one agent on or off for the whole account and holds its settings. The daily briefing and the assistant have no agent configuration.

An agent runs only when AI agents are turned on for the account and the agent’s configuration is enabled. The account-wide switch is set in Carom’s account settings, not through the API; you can read it as account.ai_agents_enabled on Retrieve your key’s user, which also lists which agents are on. Agents belong to the account, and users can’t opt out of them individually. Both endpoints require an account admin; other keys get 403 permission_denied.

An agent’s settings decide which changes it makes on its own and which wait for a person, and are separate from each user’s assistant settings, which control the chat assistant.

#The agent configuration object

Whether one agent runs for the account, and its settings.

Agents

Slug	What it does	Default
`auto_tag`	Applies tags to incoming email threads.	Enabled
`auto_task`	Proposes tasks that incoming email asks for, and proposes completing tasks the email reports as done.	Enabled
`auto_summarize`	Writes short summaries of incoming messages and threads.	Enabled
`auto_deal`	Proposes new deals and changes to existing deals from incoming email.	Enabled
`auto_enrich`	Fills in the name and description of organizations that Carom creates from email domains, using each organization’s website. Turning it on also fills in existing organizations that have no description.	Enabled
`auto_meeting`	Summarizes meeting transcripts and proposes tasks for the commitments made in them.	Enabled

Settings

Most settings are levels. At off the agent doesn’t make that kind of change. At suggest it records a pending proposal for a person to accept. At auto it makes the change and records a proposal with status auto_applied, which can be reviewed and undone. Some settings stop short of auto; each setting’s allowed_values in the response is authoritative.

Agent	Setting	What it controls	Default	Allowed values
`auto_tag`	`create_new_tags`	Whether the agent may create tags the account doesn’t have yet. When false it only applies existing tags.	`true`	`true`, `false`
`auto_task`	`create_tasks`	Tasks that incoming email asks for.	`suggest`	`off`, `suggest`
`auto_task`	`complete_tasks`	Completing tasks that incoming email reports as done.	`suggest`	`off`, `suggest`
`auto_deal`	`create_deals`	New deals.	`suggest`	`off`, `suggest`, `auto`
`auto_deal`	`advance_stages`	Moving a deal to another stage.	`suggest`	`off`, `suggest`, `auto`
`auto_deal`	`close_deals`	Marking a deal won or lost.	`suggest`	`off`, `suggest`
`auto_deal`	`fill_fields`	Filling in a deal’s empty amount or expected close date.	`auto`	`off`, `suggest`, `auto`
`auto_meeting`	`create_tasks`	Tasks for commitments made in meetings.	`auto`	`off`, `suggest`, `auto`

auto_summarize and auto_enrich have no settings.

Attributes

idstring · uuid · nullable

Unique identifier for the configuration. Null for an agent the account has never configured.
agent_slugstring

Which agent this configures: one of the slugs in the table above.
enabledboolean

Whether the agent runs for this account.
configobject · nullable

The settings that have been saved, keyed by setting name, such as {"create_new_tags": false}. A setting that isn’t here takes its default. Read settings for the value in effect.
settingsarray of objects

Every setting the agent has, with the value in effect. Empty for an agent with no settings.
Show 4 child attributesHide child attributes
- keystring
  The setting’s name, as listed in the settings table above.
- valuestring or boolean
  The saved value, or the default when none is saved.
- defaultstring or boolean
- allowed_valuesarray of strings or booleans
  The values the setting accepts.
created_atstring · date-time · nullable

Null for an agent the account has never configured.
updated_atstring · date-time · nullable

The agent configuration object

{
  "id": "4b6d8f0b-2d4f-4b6d-9f0b-3d5f7b9d1f24",
  "agent_slug": "auto_tag",
  "enabled": true,
  "config": {
    "create_new_tags": false
  },
  "settings": [
    {
      "key": "create_new_tags",
      "value": false,
      "default": true,
      "allowed_values": [true, false]
    }
  ],
  "created_at": "2026-06-02T17:20:08.619Z",
  "updated_at": "2026-09-14T19:47:31.476Z"
}

get/agent_configurations Read key

#List agent configurations

Returns one configuration for every agent, in the order of the table of agents, in one response; the list isn’t paginated. An agent the account has never configured is listed as enabled with its default settings, and with a null id, created_at, and updated_at.

Returns

collectionobject
Show 2 child attributesHide child attributes
- recordsarray of agent configurations
- total_resultsinteger
  How many configurations are in records.

Errors

403permission_deniedYour key’s user isn’t an account admin.

get/agent_configurations

curl https://api.carom.io/agent_configurations \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "collection": {
    "total_results": 6,
    "records": [
      {
        "id": "4b6d8f0b-2d4f-4b6d-9f0b-3d5f7b9d1f24",
        "agent_slug": "auto_tag",
        "enabled": true,
        "config": {
          "create_new_tags": false
        },
        "settings": [
          { "key": "create_new_tags", "value": false, "default": true, "allowed_values": [true, false] }
        ],
        "created_at": "2026-06-02T17:20:08.619Z",
        "updated_at": "2026-09-14T19:47:31.476Z"
      },
      {
        "id": null,
        "agent_slug": "auto_task",
        "enabled": true,
        "config": {},
        "settings": [
          { "key": "create_tasks", "value": "suggest", "default": "suggest", "allowed_values": ["off", "suggest"] },
          { "key": "complete_tasks", "value": "suggest", "default": "suggest", "allowed_values": ["off", "suggest"] }
        ],
        "created_at": null,
        "updated_at": null
      },
      …
    ]
  }
}

patch/agent_configurations/{agent_slug} Write key

#Update an agent configuration

Turns an agent on or off, or changes its settings. Fields you leave out keep their values, and settings you leave out of config keep theirs.

Path parameters

agent_slugstringrequired

One of the slugs listed on the agent configuration object. Any other slug returns 404 record_not_found.

Request body application/json

agent_configurationobjectrequired
Show 2 child attributesHide child attributes
- enabledboolean
- configobject
  
  Settings to change, keyed by setting name, with at least one key. Each key must be one of the agent’s settings and each value one of that setting’s allowed_values, as listed in the settings table. Otherwise the request returns 400 invalid_request and nothing is saved.

Returns

The agent configuration object, wrapped in agent_configuration.

Errors

400invalid_requestThe body has no agent_configuration object, enabled isn’t a boolean, or config is empty, not an object, or has a key the agent doesn’t have or a value that setting doesn’t allow.
403permission_deniedYour key’s user isn’t an account admin.
404record_not_foundagent_slug isn’t one of the listed slugs.

patch/agent_configurations/{agent_slug}

curl -X PATCH https://api.carom.io/agent_configurations/auto_deal \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_configuration": {
      "enabled": true,
      "config": { "advance_stages": "auto" }
    }
  }'

Response200

{
  "agent_configuration": {
    "id": "8f0b2d4f-6b8d-4f0b-8d4f-7b9d1f3b5d61",
    "agent_slug": "auto_deal",
    "enabled": true,
    "config": {
      "create_deals": "off",
      "advance_stages": "auto"
    },
    "settings": [
      { "key": "create_deals", "value": "off", "default": "suggest", "allowed_values": ["off", "suggest", "auto"] },
      { "key": "advance_stages", "value": "auto", "default": "suggest", "allowed_values": ["off", "suggest", "auto"] },
      { "key": "close_deals", "value": "suggest", "default": "suggest", "allowed_values": ["off", "suggest"] },
      { "key": "fill_fields", "value": "auto", "default": "auto", "allowed_values": ["off", "suggest", "auto"] }
    ],
    "created_at": "2026-06-02T17:20:08.619Z",
    "updated_at": "2026-09-19T10:03:52.127Z"
  }
}