API Reference

RESTful API for managing AI agents, organizations, and fleet operations.

Base URL

https://api.agent.ceo

All endpoints are relative to this base URL. The API also supports relative paths when accessed through the Next.js proxy.

Authentication

Most endpoints require a Firebase JWT token passed as a Bearer token in the Authorization header.

// Get token from Firebase Auth
const token = await firebase.auth().currentUser.getIdToken();

// Include in requests
fetch("https://api.agent.ceo/api/v1/organizations/{org_id}/agents", {
  headers: {
    "Authorization": "Bearer " + token,
    "Content-Type": "application/json"
  }
});

Note: Tokens expire after 1 hour. Use getIdToken(true) to force-refresh an expired token.

Endpoints

GET/api/v1/health

Health check

Returns the health status of the API gateway. No authentication required.

Responses

200Healthy

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 86400
}

POST/api/v1/organizations/{org_id}/agents Auth required

Create agent

Create a new agent within an organization. Requires org owner role.

Request Body

Field	Type	Required	Description
name	string	required	Display name for the agent
role	string	required	Agent role (e.g. ceo, cto, developer, devops, qa)
model	string	optional	Model ID (default: claude-sonnet-4-6)
tools	string[]	optional	List of enabled tools (e.g. bash, read, edit, write)
system_prompt	string	optional	Custom system prompt for the agent

Example

{
  "name": "Dev Agent",
  "role": "developer",
  "model": "claude-sonnet-4-6",
  "tools": [
    "bash",
    "read",
    "edit",
    "write"
  ],
  "system_prompt": "You are a senior full-stack developer."
}

Responses

201Agent created

{
  "agent_id": "agent-abc123",
  "name": "Dev Agent",
  "role": "developer",
  "status": "provisioning"
}

409Duplicate role — an agent with this role already exists in the organization

422Validation error — name and role are required

403Forbidden — user is not the org owner

GET/api/v1/organizations/{org_id}/agents Auth required

List agents

List all agents in an organization with their current status.

Responses

200Agent list

{
  "agents": [
    {
      "id": "agent-abc123",
      "name": "Dev Agent",
      "role": "developer",
      "status": "running",
      "uptime": 99.5,
      "restarts": 0
    },
    {
      "id": "agent-def456",
      "name": "QA Bot",
      "role": "qa",
      "status": "stopped",
      "restarts": 2
    }
  ]
}

PATCH/api/v1/organizations/{org_id}/agents/{role} Auth required

Update agent

Update an agent's configuration. Only provided fields are changed.

Request Body

Field	Type	Required	Description
name	string	optional	New display name
model	string	optional	New model ID
system_prompt	string	optional	New system prompt
tools	string[]	optional	Updated tool list

Example

{
  "name": "Senior Dev Agent",
  "model": "claude-opus-4-6"
}

Responses

200Agent updated

{
  "agent_id": "agent-abc123",
  "name": "Senior Dev Agent",
  "role": "developer",
  "status": "running"
}

404Agent not found

DELETE/api/v1/organizations/{org_id}/agents/{role} Auth required

Delete agent

Soft-delete an agent. The agent is stopped and marked as deleted but can be restored within 30 days.

Responses

200Agent deleted

{
  "success": true,
  "message": "Agent deleted"
}

404Agent not found

POST/api/v1/organizations/{org_id}/agents/{role}/restart Auth required

Restart agent

Restart a running or stopped agent. The agent process is terminated and re-launched with its current configuration.

Responses

200Agent restarted

{
  "success": true,
  "status": "restarting"
}

404Agent not found

GET/api/v1/fleet/status Auth required

Fleet status (admin)

Get an overview of all running agents across the platform. Requires admin privileges.

Responses

200Fleet overview

{
  "total_agents": 42,
  "running": 38,
  "stopped": 3,
  "error": 1,
  "organizations": 5
}

OpenAPI Specification

Download the full OpenAPI 3.0 spec for use with Postman, Insomnia, or code generators.

Download OpenAPI Spec Get API Access

Docs · Privacy · Terms · Security