Agents

An agent is a configured persona that runs against a chosen model. Every org has one default agent (Ala) that is auto-provisioned and cannot be deactivated, deleted, renamed off its slug, or moved to a different model. All other agents are CRUD-able within the workspaces the caller can access.

Endpoints

:id may be either the agent's UUID or its slug.

List agents

GET /api/v1/agents returns agents belonging to the caller's org and workspace, ordered by updatedAt descending. The default Ala agent is auto-created on the first call and is always present in the list.

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "orgId": "uuid",
        "workspaceId": "uuid|null",
        "name": "Ala",
        "slug": "ala",
        "description": "string|null",
        "avatar": "string",
        "model": "grok-3",
        "systemPrompt": "string|null",
        "allowedTools": ["..."],
        "allowedPeers": ["..."],
        "allowedConnectors": ["..."],
        "isActive": true,
        "settings": { "voice": { "...": "..." } },
        "createdAt": "...",
        "updatedAt": "..."
      }
    ]
  }
}

Create agent

POST /api/v1/agents

A unique slug is generated from name. The agent is placed in the caller's current workspace.

Response (201): the created agent record (same shape as list items).

curl -X POST https://alumia.com/api/v1/agents \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
  "name": "Research Assistant",
  "model": "grok-3",
  "systemPrompt": "You help with literature reviews."
}'

Get agent

GET /api/v1/agents/:id — Returns a single agent or 404 if not visible to the caller.

Update agent

PATCH /api/v1/agents/:id

Accepts any subset of: name, slug, description, systemPrompt, model, settings, allowedTools, allowedPeers, allowedConnectors, isActive, avatar. Updating slug triggers a uniqueness check within the org.

Ala enforces extra constraints:

• isActive: false is rejected (FORBIDDEN).
• model must equal Ala's locked model ID; any other value is rejected.
• slug updates are silently dropped.

Response: the updated agent record.

Delete agent

DELETE /api/v1/agents/:id — Soft-deletes the agent (deletedAt set). Deleting Ala returns 403 FORBIDDEN.

Response:

{ "success": true, "data": { "deleted": true } }

Agent sessions, messages, peers

• GET /api/v1/agents/:id/sessions — All non-deleted sessions where this agent is a participant, ordered by updatedAt desc.
• GET /api/v1/agents/:id/messages?limit=N — Up to limit (1–100, default 50) most recent agent-authored messages from sessions whose metadata.relationship = 'peer'. Each item includes fromAgentName, fromAgentAvatar, and isSelf.
• GET /api/v1/agents/:id/peers — Agents this agent may message based on its allowedPeers list.

Errors