Archive or Delete an Agent

There is no REST endpoint for deletion yet. Instead, soft deletes are built into every table through the shared timestamps helper (packages/server/src/db/schema/columns.helpers.ts). Services explicitly drop the deletedAt field when returning data, so any row with a non-null deleted_at is effectively hidden.

Soft-delete an agent

Run the query below via pnpm db:studio, psql, or your favorite SQL client:

UPDATE agents
SET deleted_at = NOW()
WHERE id = 'REPLACE_WITH_AGENT_UUID';

All reads (getAllAgents, getAgentById, etc.) automatically exclude the deleted_at column and therefore treat the row as archived. The LiveKit agent will fail to fetch configs for archived agents because /api/agents/by-phone/:phoneNumber looks up by phone number and still requires the row to exist. After soft-deleting, remember to deprovision the phone so Twilio and LiveKit resources are released.

Restore an agent

UPDATE agents
SET deleted_at = NULL
WHERE id = 'REPLACE_WITH_AGENT_UUID';

This mirrors the "undelete" behavior frameworks typically provide.

Remove an entire company

Deleting a company cascades to its agents because agents.companyId references companies with onDelete: "cascade". Use caution—this permanently removes child rows:

DELETE FROM companies
WHERE id = 'REPLACE_WITH_COMPANY_UUID';

Back up any agent YAML files before running the command so you can recreate them later.

Until the REST API exposes /api/agents/:id and /api/companies/:id DELETE routes, direct SQL is the safest way to archive data. Keep these commands in a runbook and require peer review before executing them in production.