Polysona Agents and System Status REST API Reference

The agents and status endpoints give you visibility into the health of Polysona’s five built-in agents and the overall state of your local installation. Agent status reports whether each agent’s Markdown definition file and corresponding skill file exist on disk. The system status endpoint surfaces counts and timestamps that summarize the current state of your persona and content data.

GET /api/agents/status

Returns the status of all five Polysona agents. For each agent, the response includes whether its agent definition file (agents/<name>.md) and skill file (under skills/) exist on disk. The status field is always "idle" in the current version — runtime execution state is not yet tracked by the API.

curl http://localhost:3000/api/agents/status

Example response

[
  {
    "name": "profiler",
    "description": "Deep psychology interviewer",
    "badge": "10 frameworks",
    "status": "idle",
    "agentFileExists": true,
    "skillFileExists": true,
    "skillCount": 1,
    "lastActivity": null
  },
  {
    "name": "trendsetter",
    "description": "Trend detector",
    "badge": "WebSearch",
    "status": "idle",
    "agentFileExists": true,
    "skillFileExists": false,
    "skillCount": 0,
    "lastActivity": null
  },
  {
    "name": "content-writer",
    "description": "Platform content generator",
    "badge": "5 platforms",
    "status": "idle",
    "agentFileExists": true,
    "skillFileExists": true,
    "skillCount": 1,
    "lastActivity": null
  },
  {
    "name": "virtual-follower",
    "description": "QA simulator",
    "badge": "context: fork",
    "status": "idle",
    "agentFileExists": true,
    "skillFileExists": true,
    "skillCount": 1,
    "lastActivity": null
  },
  {
    "name": "admin",
    "description": "Publisher and tracker",
    "badge": "feedback loop",
    "status": "idle",
    "agentFileExists": false,
    "skillFileExists": false,
    "skillCount": 0,
    "lastActivity": null
  }
]

The five agents are always returned in the following fixed order:

Name	Description	Badge	Skill File Path
`profiler`	Deep psychology interviewer	`10 frameworks`	`skills/interview/SKILL.md`
`trendsetter`	Trend detector	`WebSearch`	`skills/trend/SKILL.md`
`content-writer`	Platform content generator	`5 platforms`	`skills/content/SKILL.md`
`virtual-follower`	QA simulator	`context: fork`	`skills/qa/SKILL.md`
`admin`	Publisher and tracker	`feedback loop`	`skills/publish/SKILL.md`

(array)

object[]

Array of agent status objects, one per agent, in the fixed order listed above.

Show agent status object

name

string

Agent identifier. One of profiler, trendsetter, content-writer, virtual-follower, or admin.

description

string

Short human-readable description of the agent’s role.

badge

string

Short capability badge displayed in the dashboard (e.g. "10 frameworks", "WebSearch").

status

string

Current execution state. Always "idle" in the current version of Polysona.

agentFileExists

boolean

Whether the agent’s Markdown definition file exists at agents/<name>.md.

skillFileExists

boolean

Whether the agent’s skill file exists at its expected path under skills/. Requires both the skill subdirectory and the SKILL.md file to be present.

skillCount

number

1 if the skill subdirectory exists under skills/, 0 otherwise.

lastActivity

null

Always null in the current version. Reserved for future runtime tracking.

GET /api/status

Returns a high-level summary of the Polysona installation: how many persona directories exist, how many content files are present across both pipeline stages, when any persona or content file was last modified, and the current Polysona version.

curl http://localhost:3000/api/status

Example response

{
  "personaCount": 2,
  "contentCount": 5,
  "lastActivity": "2026-03-29T08:34:12.000Z",
  "version": "1.3.0"
}

personaCount

number

Number of subdirectories found under personas/. Each directory is counted as one persona regardless of which PLOON files it contains.

contentCount

number

Combined count of non-hidden files in content/drafts/ and content/published/. Equivalent to drafts.length + published.length.

lastActivity

string | null

ISO 8601 timestamp of the most recently modified file across all persona PLOON files (persona.md, nuance.md, accounts.md) and all draft and published content files. Returns null if no files are found.

version

string

The running Polysona version. Currently "1.3.0".

Use GET /api/status as a lightweight health check in scripts or CI workflows. A non-null lastActivity combined with a non-zero personaCount confirms that the installation has been set up and is actively in use.

REST API

Documentation Index

​GET /api/agents/status

​GET /api/status

Build docs developers (and LLMs) love

GET /api/agents/status

GET /api/status