PaperClipAI/docs/api/agents.md at fd9985b5713605ce5eff3c458620490f7bb5dfcb

0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-13 07:12:00 +01:00

Files

T

TonioandPaperclip 9dfdeaad86 Refine agent workspaces and organization charts (#20973 )

Refine agent details, identity editing, responsive controls, and organization charts with three card tiers, clearer save feedback, and stable filtering.

Guard instruction-file renames and root configuration updates in one transaction through the agent lifecycle integration, preserving conflict checks, rollback, and configuration history.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-11-12 01:23:59 +00:00

4.1 KiB

Raw Blame History

title, summary

title	summary
Agents	Agent lifecycle, configuration, keys, and heartbeat invocation

Manage AI agents (employees) within a company.

List Agents

GET /api/companies/{companyId}/agents

Returns all agents in the company.

This route does not accept query filters. Unsupported query parameters return 400.

Get Agent

GET /api/agents/{agentId}

Returns agent details including chain of command.

Read execution environment identity

Board users with organization access can list environments with GET /api/companies/{companyId}/environments or read one with GET /api/environments/{environmentId}. These routes read instance environments. A plugin environment includes pluginDriver, with pluginKey and driverKey, so clients can match the agent's defaultEnvironmentId to the driver even when configuration is redacted. This field does not contain driver configuration, environment variables, or credentials. An agent with no default inherits the instance default.

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": "cto" },
    { "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.

Clear Agent Error

POST /api/agents/{agentId}/clear-error

Moves an agent from error back to idle without deleting run history or runtime diagnostics. Only agents currently in error can be cleared.

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.

List Adapter Models

GET /api/companies/{companyId}/adapters/{adapterType}/models

Returns selectable models for an adapter type.

For codex_local, models are merged with OpenAI discovery when available.
For opencode_local, models are discovered from opencode models and returned in provider/model format.
opencode_local does not return static fallback models; if discovery is unavailable, this list can be empty.

Config Revisions

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

View and roll back agent configuration changes.

Rename an instruction file

Use PUT /api/agents/{id}/instructions-bundle/file with path, renameTo, content, and the source file's current baseHash. Use null only when the configured root file is missing; a concurrently created root returns 409. Renames require the same instruction configuration permission as file writes. The managed file store checks the source hash and destination under the agent write lock, then updates the file and the configured root path together. A stale source or occupied name returns 409. External bundles must be migrated to managed storage before using this operation. A successful response contains the renamed file detail.

4.1 KiB Raw Blame History