Skip to content

Agent Administration ​

GhostAI’s agent administration APIs register agent identities per organization. Registered agents are the basis for attributing traffic (for example via X-Agent-Id) on OpenAI- and Anthropic-compatible APIs, policy enforcement, and audit trails.

Registering agents ​

Create a registration with POST /api/admin/agents (admin-authenticated). Required and optional fields include:

FieldNotes
nameHuman-readable name (required, length limits apply).
descriptionOptional longer text.
frameworkSee below; defaults to custom if omitted.
agent_typeOne of: autonomous, semi-autonomous, tool-calling (default).

Successful registration returns 201 with a server-assigned agent id, organization_id, initial status (typically active), and timestamps.

Framework selection ​

Set framework to match how the agent was built. Supported values:

ValueTypical stack
langchainLangChain
crewaiCrewAI
autogenAutoGen
llamaindexLlamaIndex
openclawOpenClaw / GhostClaw integrations
customIn-house or other frameworks

Agent types ​

agent_type classifies behavior for policy and reporting:

  • tool-calling — Primarily invokes tools/APIs when prompted.
  • semi-autonomous — Mixed planning with user or system checkpoints.
  • autonomous — Broader autonomy within configured guardrails.

Use the value that best matches your deployment’s risk review.

Status management ​

Agent records support a status lifecycle:

StatusMeaning
activeNormal operation; identity is valid for attribution and policy checks.
suspendedTemporarily disabled; use when pausing without deleting history.
revokedPermanently withdrawn (see delete behavior below).

List agents with an optional filter: GET /api/admin/agents?status=active (or suspended / revoked).

Updates use PATCH /api/admin/agents/{agent_id} with partial fields including status.

API reference (CRUD) ​

Routes are under /api/admin/agents and require admin access.

MethodPathPurpose
POST/api/admin/agentsRegister a new agent (201 on success).
GET/api/admin/agentsList agents for the org; optional status query.
GET/api/admin/agents/{agent_id}Get one registration.
PATCH/api/admin/agents/{agent_id}Update name, description, framework, type, or status.
DELETE/api/admin/agents/{agent_id}Revoke the agent (sets status to revoked).

DELETE returns 204 No Content

DELETE /api/admin/agents/{agent_id} responds with 204 and no response body. Clients should treat 204 as success and refresh lists or local state from a subsequent GET if they need the updated record.

Deletion semantics in the API mark the agent as revoked (soft revoke) while preserving the row for audit continuity—confirm behavior in your environment if you rely on hard deletes.

SOC 2 Type II Certified | BAA Available | HIPAA-Ready