folder_assign

Files agents under one of your folders, moving any that are already filed elsewhere. Passing an empty folder unfiles them instead, returning them to the dashboard’s Unfiled group. Equivalent to murmur folder assign and murmur folder unfile in the CLI. The folder must already exist; create it with folder. Naming a missing folder returns an error that lists the existing folders instead of creating one. Folders organize only the current person’s sidebar.

Parameters

Name	Type	Required	Description
`folder`	string	yes	The folder to file these agents under, by name, as listed by `spawn_profiles`. Pass `""` to unfile them instead. Omitting it is an error, not an unfile.
`slugs`	string[]	yes	Agent slugs to file. Each must be a top-level agent you can read; use an absolute path like `/w/{workspace}/{owner_provider}/{account}/{slug}` for an agent outside your own path. They must all belong to one workspace.
`workspace`	string	no	Workspace name. Overrides the session default. Required only when nothing else supplies one: off a VM, with no session default, and with slugs that are not `/w/{workspace}/...` paths.

folder is required and "" is a real value: it unfiles. Omitting the parameter is rejected rather than treated as "", so a call that forgets it cannot silently empty a folder.

Folders hold top-level agents. A child agent renders under its root in the dashboard, so it cannot be filed on its own.

Response

Field	Type	Description
`updated_members`	number	How many agents changed folder, counting those filed, moved, and unfiled. An agent already in the named folder is not counted, so `0` means the call was a no-op rather than a failure.

Examples

File two agents

{
  "folder": "Release 4.2",
  "slugs": ["fix-auth", "bump-deps"],
  "workspace": "backend"
}

Response:

{
  "updated_members": 2
}

Unfile an agent

{
  "folder": "",
  "slugs": ["bump-deps"]
}

Errors

Code	Meaning	What to do
none	`folder is required ...` or `slugs is required`: a required argument was omitted.	Pass `folder` (or `""` to unfile) and at least one slug.
none	`no folder named "<name>" ...`: no folder of yours has that name.	The message lists the folders you do have. Create one with `folder`.
`INVALID_ARGUMENT`	An agent is not top-level, an agent is named twice, or the agents span two workspaces.	The error says which. List agents with `ls`.
`NOT_FOUND`	No agent with that slug exists.	Check the slug with `ls`.
`PERMISSION_DENIED`	You cannot read one of the named agents.	Filing requires `agent.read` on every agent named.
`FAILED_PRECONDITION`	The caller has no personal identity to hold folders.	Folders belong to a person; an agent running on a VM has no personal identity and cannot hold them.

murmur folder assign: equivalent CLI command
murmur folder unfile: the CLI’s spelling for folder: ""
folder: create the folder first
spawn: file a new agent at spawn time via folder

Getting started

Core concepts

Integrations

Guides

Parameters

Response

Examples

File two agents

Unfile an agent

Errors

​Parameters

​Response

​Examples

​File two agents

​Unfile an agent

​Errors

​Related

Parameters

Response

Examples

File two agents

Unfile an agent

Errors

Related