Skip to main content

​
Agent Endpoints

Manage agents via the REST API.

​
Create Agent

Endpoint: 
POST /api/v2/agents
Headers: 
Authorization: Bearer mk_your_api_key
Content-Type: application/json
Request Body: 
{
  "agent_id": "customer-support",
  "description": "Handles customer inquiries (optional)"
}
Response (201 Created): 
{
  "agent_id": "customer-support",
  "created_at": "2025-03-30T16:30:00Z",
  "namespace": "memanto_agent_customer-support",
  "status": "active"
}
Example: 
import httpx

response = httpx.post(
    "http://localhost:8000/api/v2/agents",
    json={"agent_id": "customer-support"},
    headers={"Authorization": f"Bearer {api_key}"}
)
agent = response.json()

​
List Agents

Endpoint: 
GET /api/v2/agents
Headers: 
Authorization: Bearer mk_your_api_key
Query Parameters:
  • limit (int, optional) - Results per page (default: 10)
  • offset (int, optional) - Pagination offset (default: 0)
  • sort (string, optional) - Sort by: created, name, recent
Response (200 OK): 
{
  "agents": [
    {
      "agent_id": "customer-support",
      "created_at": "2025-03-25T10:30:00Z",
      "memory_count": 42,
      "last_active": "2025-03-30T14:22:00Z"
    },
    {
      "agent_id": "project-manager",
      "created_at": "2025-03-20T09:15:00Z",
      "memory_count": 18,
      "last_active": "2025-03-28T11:45:00Z"
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}
Example: 
response = httpx.get(
    "http://localhost:8000/api/v2/agents",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {api_key}"}
)
agents = response.json()["agents"]

​
Get Agent

Endpoint: 
GET /api/v2/agents/{agent_id}
Path Parameters:
  • agent_id (string) - Agent identifier
Headers: 
Authorization: Bearer mk_your_api_key
Response (200 OK): 
{
  "agent_id": "customer-support",
  "created_at": "2025-03-25T10:30:00Z",
  "memory_count": 42,
  "memory_breakdown": {
    "fact": 15,
    "preference": 8,
    "event": 12,
    "commitment": 4,
    "decision": 3
  },
  "last_active": "2025-03-30T14:22:00Z",
  "last_memory": "2025-03-30T14:45:00Z"
}
Example: 
response = httpx.get(
    "http://localhost:8000/api/v2/agents/customer-support",
    headers={"Authorization": f"Bearer {api_key}"}
)
agent_details = response.json()

​
Delete Agent

Endpoint: 
DELETE /api/v2/agents/{agent_id}
Path Parameters:
  • agent_id (string) - Agent identifier
Headers: 
Authorization: Bearer mk_your_api_key
Response (204 No Content): 
(empty body)
Error (Agent not found): 
{
  "status": "error",
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent 'xyz' not found"
  }
}
Example: 
response = httpx.delete(
    "http://localhost:8000/api/v2/agents/old-agent",
    headers={"Authorization": f"Bearer {api_key}"}
)
if response.status_code == 204:
    print("Agent deleted")
⚠️ Warning: Deleting an agent permanently removes all its memories. Cannot be undone.

​
Workflow: Complete Agent Lifecycle

import httpx

api_key = "mk_your_api_key"
base_url = "http://localhost:8000/api/v2"
headers = {"Authorization": f"Bearer {api_key}"}

# 1. Create agent
create_resp = httpx.post(
    f"{base_url}/agents",
    json={"agent_id": "new-agent"},
    headers=headers
)
print(f"Created: {create_resp.json()['agent_id']}")

# 2. List agents
list_resp = httpx.get(
    f"{base_url}/agents",
    headers=headers
)
print(f"Total agents: {list_resp.json()['total']}")

# 3. Get agent details
get_resp = httpx.get(
    f"{base_url}/agents/new-agent",
    headers=headers
)
print(f"Memory count: {get_resp.json()['memory_count']}")

# 4. Delete agent
delete_resp = httpx.delete(
    f"{base_url}/agents/new-agent",
    headers=headers
)
if delete_resp.status_code == 204:
    print("Agent deleted")

​
Next Steps