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 one that does not exist is an error listing the folders that do, never a silent create: a folder is one person’s own organization of their 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.

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
`INVALID_ARGUMENT`	No folder of yours has that name, `folder` was omitted, an agent is not top-level, an agent is named twice, or the agents span two workspaces.	The error says which. List folders with `spawn_profiles` and 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

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