Update prospect list

Outcome

Rename a retained active list or edit its description.

Before you start

• Verify the environment, credential, authorized organization and the published action permission workspace:write.
• Discover an accessible Engage workspace and bind resourceType=workspace and its resourceId separately from action input. Fixture identifiers grant no access.
• Approve the exact mutation and its effects before CLI --confirm or MCP confirm:true. This documentation does not authorize outreach.

Discover the target

• Discover list id through lists.list, then read lists.get in the selected workspace and inspect archivedAt. Retain the current name, description and active membership state before planning.

topolo whoami --json
topolo actions get app_topolo_engage.lists.update --json
topolo workspaces list topolo-engage --json

Input fields

Validate, plan and execute

Set ENGAGE_WORKSPACE_ID to the identifier of your selected workspace. Prepare payload.json from the current input schema and discovered identifiers. Use the same payload for validation, planning and execution.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions validate app_topolo_engage.lists.update --data @payload.json --json
topolo actions plan app_topolo_engage.lists.update --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --confirm --json

Review the plan and obtain approval for the exact effects before executing the unchanged request.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions call app_topolo_engage.lists.update --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --confirm --json

For MCP, use topolo_get_action, topolo_validate_action, topolo_plan_action and topolo_call_action. Pass the selected resource context separately; confirm:true is required for mutations.

Worked requests and responses

Captured lists.update · HTTP 200

Action input

{
  "id": "list_1",
  "description": "Seed"
}

Actual local response

{
  "list": {
    "id": "list_1",
    "name": "Founders",
    "description": "Seed",
    "memberCount": 0,
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": null
  }
}

Source test: audience routes > lists > creates, lists, edits and archives a list. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured lists.update · HTTP 200

Action input

{
  "id": "list_1",
  "name": "VCs"
}

Actual local response

{
  "list": {
    "id": "list_1",
    "name": "VCs",
    "description": "Seed",
    "memberCount": 0,
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": null
  }
}

Source test: audience routes > lists > creates, lists, edits and archives a list. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Effects and response meaning

• Supplied name/description replace retained values; omitted values remain unchanged. Null or blank clears description. At least one editable field is required; archived lists are refused.
• Returns list with updatedAt and current active memberCount. It does not change memberships or send messages and has no expected-version compare-and-swap input.

Verify the result

• Read lists.get and compare supplied and retained fields, plus archivedAt. Do not infer membership changes from metadata updatedAt.

Recover

Read lists.get after an uncertain response and reconcile intended fields before retrying. Restoring a reviewed prior name/description is a separately approved update; inspect concurrent changes first.

Refused responses

Captured lists.update · HTTP 422

Action input

{
  "id": "list_1"
}

Actual local response

{
  "error": {
    "code": "invalid_input",
    "message": "Provide a name or a description to change."
  }
}

Source test: audience routes > lists > creates, lists, edits and archives a list. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured lists.update · HTTP 409

Action input

{
  "id": "list_1",
  "name": "x"
}

Actual local response

{
  "error": {
    "code": "state_conflict",
    "message": "Archived lists cannot be changed."
  }
}

Source test: audience routes > lists > creates, lists, edits and archives a list. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Error recovery

• HTTP 403 permission_denied: Stop and inspect the permission required by this action in the current credential. Do not broaden permissions or switch organization automatically.
• HTTP 422 invalid_action_input: Correct the request against the current input schema and validate it again before planning.
• HTTP 422 invalid_input: Supply at least one actual editable field: contact profile/custom or list name/description. An id-only edit is refused; validate the intended payload again.
• HTTP 409 state_conflict: Read the exact retained contact or list and inspect archivedAt. Archived records cannot be edited or have list memberships changed; repeated archive is refused. Do not invent an unarchive operation.

Related actions

• Get prospect list

Evidence and limits

• contracts/audience.mjs

• contracts/audience-filter.mjs

• apps/api/src/audience/audience-routes.ts

• apps/api/src/audience/contacts-handlers.ts

• apps/api/src/audience/contact-search.ts

• apps/api/src/audience/contacts-repository.ts

• apps/api/src/audience/lists-handlers.ts

• apps/api/src/audience/lists-repository.ts

• apps/api/src/audience/filter-source.ts

• apps/api/test/audience-routes.test.ts

• apps/api/test/segments-routes.test.ts

• Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

• Widget/bootstrap use actual app handler but mocked worker runtime and app identity.

• No gateway execution, live permissions, external delivery or deployed proof.

The examples are local route captures with synthetic context and simulated providers. They do not prove live authorization, CLI/MCP gateway execution, production state or delivery.