Update Agent

Partially updates an agent by its numeric id, scoped to the workspace. All fields are optional, but at least one must be provided. Returns 404 when the agent does not exist.

Update agent

PUT/api/v2/agents/:agent_id

A signal setup cannot be updated here: use PATCH /v3/signal-setups/{id} with the same id.

Path parameters

Parameter	Type	Description
agent_id	integer	Identifier of the agent.

Request body

Field	Type	Description
name	string	Optional. Display name of the agent. Between 1 and 100 characters.
enabled	boolean	Optional. Whether the agent is active and monitoring.
parameters	object	Optional. Type-specific configuration (see below).
parameters.tracking_keywords	string[]	Keywords Sillage monitors — LinkedIn posts for `keyword_detection` and `keyword_post_search` agents, your tracked companies' job postings for `job_posting_keyword_detection` agents. Minimum 1 required.
parameters.max_posts_to_scrape	integer	Optional. Maximum number of posts to scrape per run.
parameters.start_date	string	Optional. ISO 8601 date — scrape only posts published after this date.
parameters.mode	enum (`lead_discovery`, `account_monitoring`, `all`)	Competitor agents only. What the agent does — see the note below. Send it alone or together with `target_group`, without `tracking_keywords` or `start_date`.
parameters.target_group	enum (`prospects`, `customers`, `all`)	Competitor agents only. Which people at the tracked competitor a lead-discovery run watches — see the note below. Send it alone or together with `mode`, without `tracking_keywords` or `start_date`.
watchlist_id	integer \| null	Optional. Bind the agent to a watchlist by id. The kind is derived from the agent type — `watchlist_kind` may be omitted. Pass `null` (alongside `null` `watchlist_kind`) to unbind — this resets an interaction agent to `unconfigured` (see note below).
watchlist_kind	enum (`company`, `profile`) \| null	Optional. When provided with `watchlist_id`, must match the kind implied by the agent type. Pass `null` alongside `null` `watchlist_id` to unbind. A contradicting kind returns 422.
schedule	object \| null	Optional. Turn the agent's weekly run on or off: send `{ "cadence": "weekly" }` to turn it on, or `null` to turn it off. `weekly` is the only supported cadence. Accepted only when the agent is schedulable — see Errors.

Changing what a competitor agent does

parameters.mode switches a competitor agent between the two things it can do, without recreating it — its detection history is kept.

account_monitoring — detects interactions between the competitor and your own top accounts, in both directions. No scraping, no credits.
lead_discovery — watches the competitor's team on LinkedIn and surfaces both directions: the people they comment on or react to, and the people who comment on or react to their own posts, wherever those people work. Both directions always run together. Each lead found consumes credits.
all — both at once. Only the newly discovered leads consume credits.

Switching to lead_discovery alone stops the top-account monitoring. Choose all to add lead discovery while keeping it.

mode and target_group can travel together, or on their own: a parameters object carrying tracking_keywords alongside either one returns 422, and so does sending either one for an agent that is not a competitor agent.

Changing who a competitor agent watches

parameters.target_group picks which people at the tracked competitor a lead_discovery (or all) run watches, and so whose LinkedIn interactions it reads — independent of mode, and it never resets on a mode-only update, or vice versa.

prospects — their new-business side: sales, account executives, SDR/BDR, revenue and exec leadership.
customers — their account side: account management, customer success, support.
all — both.

If this agent has never had a target_group set, a GET on it returns target_group: null alongside a resolved_target_persona inherited from an earlier version. Sending target_group here replaces that inherited list for good — the group you choose is what every future run uses, and the agent stops reading null.

Unbinding an interaction agent resets its type

Unbinding an interaction-type agent (competitor, partner, customer, influencer, or champion) by sending watchlist_id: null sets its type to unconfigured, empties its parameters, and stops its monitoring until you bind a new watchlist. The previous type is not remembered — bind a watchlist again with watchlist_id to reconfigure the agent.

Example request

curl -X PUT "https://api.getsillage.com/api/v2/agents/42" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "parameters": {
      "tracking_keywords": ["fundraising", "series a", "\"series a\"", "hiring sales", "product launch"]
    }
  }'

Example response

{
  "data": {
    "id": 42,
    "name": "LinkedIn keyword monitor",
    "type": "keyword_detection",
    "enabled": true,
    "schedulable": false,
    "schedule": null,
    "parameters": {
      "tracking_keywords": ["fundraising", "series a", "hiring sales", "product launch"]
    },
    "watchlist_kind": null,
    "watchlist_id": null,
    "created_at": "2026-06-18T10:00:00.000Z",
    "updated_at": "2026-06-18T11:30:00.000Z"
  }
}

Response fields

Field	Type	Description
data.id	integer	Identifier of the agent.
data.name	string	Display name of the agent.
data.type	string	Agent type.
data.enabled	boolean	Whether the agent is currently active.
data.schedulable	boolean	Whether this agent can run on a weekly schedule. `true` for `keyword_post_search` agents, and for `competitor` agents whose `mode` is `lead_discovery` or `all`; `false` for every other agent type. Read-only — setting `schedule` on an agent where this is `false` returns 422.
data.schedule	object \| null	The agent's weekly run schedule. `{ "cadence": "weekly" }` when weekly runs are on, `null` when they are off. `weekly` is the only cadence supported today.
data.parameters	object	The configured parameters, echoed back.
data.watchlist_kind	string	Kind (`company`/`profile`) of the bound watchlist, or `null` when unbound.
data.watchlist_id	integer	Id of the bound watchlist, or `null` when the agent is unbound.
data.created_at	string	ISO 8601 creation timestamp.
data.updated_at	string	ISO 8601 last-update timestamp.

Change what a competitor agent does

curl -X PUT "https://api.getsillage.com/api/v2/agents/57" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "mode": "all" } }'

{
  "data": {
    "id": 57,
    "name": "Acme competitor watch",
    "type": "competitor",
    "enabled": true,
    "schedulable": true,
    "schedule": null,
    "parameters": {
      "mode": "all",
      "target_group": "all",
      "resolved_target_persona": ["sales", "ventes", "account executive", "..."]
    },
    "watchlist_kind": "company",
    "watchlist_id": 12,
    "created_at": "2026-06-18T10:00:00.000Z",
    "updated_at": "2026-08-26T09:15:00.000Z"
  }
}

Errors

Status	Description
401	The API key is missing or invalid.
404	The agent does not exist.
409	This is a signal setup. Update it with `PATCH /v3/signal-setups/{id}`.
422	Invalid request body — no field provided, empty `tracking_keywords`, `parameters` mixing `tracking_keywords`/`start_date` with `mode`/`target_group`, or `mode`/`target_group` sent for an agent that is not a competitor agent. Also returned when `schedule.cadence` is anything other than `weekly`, `schedule` is sent for an agent that is not `schedulable`, or `enabled: false` is combined with a non-null `schedule` in the same request.

Update Agent

On this page