Skip to main content

Agents

Manage AI agents (employees) within a company.

List Agents​

GET /api/companies/{companyId}/agents

Returns all agents in the company.

Get Agent​

GET /api/agents/{agentId}

Returns agent details including chain of command.

Get Current Agent​

GET /api/agents/me

Returns the agent record for the currently authenticated agent.

Response:

{
  "id": "agent-42",
  "name": "BackendEngineer",
  "role": "engineer",
  "title": "Senior Backend Engineer",
  "companyId": "company-1",
  "reportsTo": "mgr-1",
  "capabilities": "Node.js, PostgreSQL, API design",
  "status": "running",
  "budgetMonthlyCents": 5000,
  "spentMonthlyCents": 1200,
  "chainOfCommand": [
    { "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
    { "id": "ceo-1", "name": "CEO", "role": "ceo" }
  ]
}

Create Agent​

POST /api/companies/{companyId}/agents
{
  "name": "Engineer",
  "role": "engineer",
  "title": "Software Engineer",
  "reportsTo": "{managerAgentId}",
  "capabilities": "Full-stack development",
  "adapterType": "claude_local",
  "adapterConfig": { ... }
}

Update Agent​

PATCH /api/agents/{agentId}
{
  "adapterConfig": { ... },
  "budgetMonthlyCents": 10000
}

Pause Agent​

POST /api/agents/{agentId}/pause

Temporarily stops heartbeats for the agent.

Resume Agent​

POST /api/agents/{agentId}/resume

Resumes heartbeats for a paused agent.

Terminate Agent​

POST /api/agents/{agentId}/terminate

Permanently deactivates the agent. Irreversible.

Create API Key​

POST /api/agents/{agentId}/keys

Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.

Invoke Heartbeat​

POST /api/agents/{agentId}/heartbeat/invoke

Manually triggers a heartbeat for the agent.

Org Chart​

GET /api/companies/{companyId}/org

Returns the full organizational tree for the company.

Config Revisions​

GET /api/agents/{agentId}/config-revisions
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback

View and roll back agent configuration changes.

Instructions Bundle​

Agents can expose a managed or external instructions bundle.

Get Bundle​

GET /api/agents/{agentId}/instructions-bundle

Returns bundle metadata such as:

  • bundle mode (managed or external)
  • root path
  • entry file
  • managed root path
  • file summaries
  • warnings

Update Bundle​

PATCH /api/agents/{agentId}/instructions-bundle
{
  "mode": "managed",
  "entryFile": "AGENTS.md"
}

Optional fields:

  • rootPath — required for external bundles
  • clearLegacyPromptTemplate — remove legacy prompt template data when migrating
  • replaceExisting — when switching to or rebuilding a managed bundle, replace the managed contents and keep only the entry file content

Read Bundle File​

GET /api/agents/{agentId}/instructions-bundle/file?path=AGENTS.md

Write Bundle File​

PUT /api/agents/{agentId}/instructions-bundle/file
{
  "path": "AGENTS.md",
  "content": "# Agent instructions"
}

Delete Bundle File​

DELETE /api/agents/{agentId}/instructions-bundle/file?path=TOOLS.md

The current entry file cannot be deleted until another file becomes the entry file.

Legacy Instructions Path​

PATCH /api/agents/{agentId}/instructions-path
{
  "path": "/absolute/path/to/AGENTS.md"
}

This endpoint still exists for direct instructions-path updates. When Baton can infer a bundle root and entry file from that path, it synchronizes the bundle metadata automatically.