Agents API

The Agents API lets you create and manage agents. All endpoints are relative to the base path /api/agents.

Tip

For agent management, use the Snippbots page in the Snippbot UI.

Endpoints

Method	Path	Description
GET	/api/agents	List all agents
POST	/api/agents	Create an agent
GET	/api/agents/{name}	Get a single agent
DELETE	/api/agents/{name}	Delete an agent
GET	/api/agents/{name}/exists	Check if an agent name is taken

Note

Agent routes use {name} (the agent’s unique name), not a numeric or prefixed ID.

---

List Agents

GET /api/agents

Returns all agents.

Response

{
  "agents": [
    {
      "name": "Assistant",
      "archetype": ["generalist"],
      "user_name": "Alice",
      "snippbot_name": "assistant",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

---

Create Agent

POST /api/agents

Creates a new agent workspace.

Request Body

Field	Type	Required	Description
snippbot_name	string	Yes	Unique machine name for the agent
user_name	string	Yes	Display name of the user/owner
archetype	string or array	Yes	Behavioral template(s). Accepts a single string or array of up to 3
profile	object	No	Additional profile configuration
evolution_choice	string	No	Evolution mode (default: check)
custom_archetype	string	No	Custom archetype description
answers	array	No	Setup wizard answers

Response

Returns the created agent object with status 201 Created.

---

Get Agent

GET /api/agents/{name}

Returns a single agent by name.

---

Check Agent Exists

GET /api/agents/{name}/exists

Returns whether an agent with the given name already exists. Useful for validating names before creation.

---

Delete Agent

DELETE /api/agents/{name}

Permanently deletes an agent and its workspace directory. All associated data (memory, chat history, workspace files) is removed.

Response

{ "deleted": true }