Agents
Register, govern, and transition AI agents through their lifecycle.
Agents are the unit of governance in Palveron. Every API call is attributed to an agent, and every agent moves through a strict lifecycle that's enforced by the gateway.
Register an agent
POST /api/v1/agents{
"name": "Customer Support Bot",
"description": "Answers tier-1 support emails using GPT-4o.",
"agent_type": "chatbot",
"risk_level": "LIMITED",
"responsible_person_id": "usr_01HVB...",
"technical_maintainer_id": "usr_01HVC...",
"data_protection_level": "PSEUDONYMIZED"
}A newly registered agent starts in PENDING_APPROVAL. For Community tier, it's auto-promoted to ACTIVE. For Business and Enterprise, an admin or compliance officer must approve.
The response returns an agent_ API key — store it immediately, it is only shown once.
Lifecycle transitions
| Endpoint | Transition | Who can call it |
|---|---|---|
POST /agents/{id}/approve | PENDING_APPROVAL → ACTIVE | admin, owner, compliance |
POST /agents/{id}/reject | PENDING_APPROVAL → REJECTED | admin, owner, compliance |
POST /agents/{id}/pause | ACTIVE → PAUSED | admin, owner, compliance |
POST /agents/{id}/resume | PAUSED → ACTIVE | admin, owner, compliance |
POST /agents/{id}/suspend | ACTIVE → SUSPENDED | admin, owner, compliance |
POST /agents/{id}/revoke | * → REVOKED (terminal) | admin, owner |
POST /agents/{id}/emergency-stop | ACTIVE → SUSPENDED + revokes all keys | admin, owner |
Every transition writes a Flare-anchored lifecycle event under EU AI Act Art. 12. Emergency-stop additionally invalidates all agent_ keys issued for the agent.
Read endpoints
| Endpoint | Returns |
|---|---|
GET /api/v1/agents | Paginated list with status, risk level, and last activity |
GET /api/v1/agents/{id} | Full agent record including governance metadata |
GET /api/v1/agents/{id}/budgets | Current request/token/cost budgets and their consumed counters |
GET /api/v1/agents/{id}/policies | Policies attached to this agent |
GET /api/v1/agents/{id}/traces?days=30 | Recent governance decisions for this agent |
Update governance metadata
PATCH /api/v1/agents/{id}Updatable fields: name, description, risk_level, data_protection_level, responsible_person_id, technical_maintainer_id, approval_authority_id, transparency_disclosure.
Changing risk_level from LIMITED to HIGH triggers a re-evaluation against EU AI Act Art. 6 / Annex III and may block the change if required fields are missing (e.g., FRIA, responsibility chain).
Errors
| Status | Code | Meaning |
|---|---|---|
400 | INVALID_RISK_LEVEL | Risk level isn't one of MINIMAL, LIMITED, HIGH, UNACCEPTABLE |
400 | INVALID_TRANSITION | The requested transition isn't valid from the current state |
403 | FRIA_REQUIRED | Activating a HIGH-risk agent without a completed FRIA |
409 | DUPLICATE_NAME | Another agent in the project already uses this name |