Skip to content

Agent Registration API ​

Register and manage agent identities per organization. Registered agents can be correlated with requests (for example via X-Agent-Id on compatible APIs). All routes require admin authentication (Authentication).

Base path: /api/admin/agents

Replace YOUR_ADMIN_TOKEN with an admin-capable Bearer token. For local development, use http://localhost:8000.

Register an agent ​

POST /api/admin/agents

Request body ​

FieldTypeRequiredDescription
namestringYesDisplay name (1–200 characters)
descriptionstringNoOptional description (up to 1000 characters)
frameworkstringNoOne of: langchain, crewai, autogen, llamaindex, openclaw, custom (default custom)
agent_typestringNoOne of: autonomous, semi-autonomous, tool-calling (default tool-calling)

Example ​

bash
curl -X POST "https://api.ghostai.com/api/admin/agents" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing automation",
    "description": "Monthly invoice summarization",
    "framework": "langchain",
    "agent_type": "tool-calling"
  }'

List agents ​

GET /api/admin/agents
GET /api/admin/agents?status=active
GET /api/admin/agents?status=suspended
GET /api/admin/agents?status=revoked

Optional query status filters to active, suspended, or revoked. Omit it to return all agents for the organization.

Example ​

bash
curl -s "https://api.ghostai.com/api/admin/agents?status=active" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Get, update, or delete an agent ​

GET    /api/admin/agents/{agent_id}
PATCH  /api/admin/agents/{agent_id}
DELETE /api/admin/agents/{agent_id}
  • PATCH accepts any of: name, description, framework, agent_type, status (active | suspended | revoked).
  • DELETE revokes the agent registration and returns 204 No Content with an empty body on success.

Examples ​

bash
curl -s "https://api.ghostai.com/api/admin/agents/agent-uuid-here" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
bash
curl -X PATCH "https://api.ghostai.com/api/admin/agents/agent-uuid-here" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "suspended"}'
bash
curl -X DELETE "https://api.ghostai.com/api/admin/agents/agent-uuid-here" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -i

A successful DELETE shows HTTP/1.1 204 with no response body.

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