Agents API
Registration, lifecycle control and key rotation for agent identities.
Registration is the only moment a private key can be returned, and only when Veefore generated it. Prefer supplying your own public_key so the private half never crosses the network at all. Lifecycle transitions are not interchangeable: pause is reversible and operational, suspend is reversible and security-driven, revoke is terminal.
Step-up required
2 endpoints in this group require a fresh step-up authentication within the last few minutes, even for a session that already holds the permission. They are marked below.
#Endpoints
| Endpoint | Permission | Notes | |
|---|---|---|---|
GET |
/v1/agents |
agent:read |
— |
POST |
/v1/agents |
agent:create |
accepts Idempotency-Key |
GET |
/v1/agents/{agentId} |
agent:read |
— |
PATCH |
/v1/agents/{agentId} |
agent:update |
— |
POST |
/v1/agents/{agentId}/pause |
agent:pause |
— |
POST |
/v1/agents/{agentId}/resume |
agent:resume |
— |
POST |
/v1/agents/{agentId}/suspend |
agent:suspend |
— |
POST |
/v1/agents/{agentId}/revoke |
agent:revoke |
step-up, high impact |
POST |
/v1/agents/{agentId}/rotate-credentials |
agent:rotate_credentials |
— |
GET |
/v1/agents/{agentId}/health |
agent:read |
— |
GET |
/v1/agents/{agentId}/authority |
delegation:read |
— |
POST |
/v1/agents/bulk |
agent:revoke |
step-up, high impact |
POST |
/v1/agents/bulk/preview |
agent:read |
— |
#What each endpoint does
#GET /v1/agents
List agents with operational columns.
Requires agent:read.
#POST /v1/agents
Register an agent, issue identity and passport.
Requires agent:create.
Request body:
json{
"name": "string",
"workspace_id": "string",
"environment_id": "string",
"capabilities": "string[]",
"public_key": "base64 SPKI?"
}
Response:
json{
"data": {
"agent": {
"id": "agt_…"
},
"private_key": "base64 PKCS8 (shown once, only if Veefore generated it)"
}
}
#GET /v1/agents/{agentId}
Read an agent.
Requires agent:read.
#PATCH /v1/agents/{agentId}
Update agent metadata.
Requires agent:update.
#POST /v1/agents/{agentId}/pause
Stop new protected execution.
Requires agent:pause.
#POST /v1/agents/{agentId}/resume
Resume a paused agent.
Requires agent:resume.
#POST /v1/agents/{agentId}/suspend
Security-restricted state.
Requires agent:suspend.
Request body:
json{
"reason": "string"
}
#POST /v1/agents/{agentId}/revoke
Terminal identity invalidation.
Requires agent:revoke. Step-up authentication is also required.
Request body:
json{
"reason": "string"
}
#POST /v1/agents/{agentId}/rotate-credentials
Rotate the agent identity key.
Requires agent:rotate_credentials.
#GET /v1/agents/{agentId}/health
Operational health report.
Requires agent:read.
#GET /v1/agents/{agentId}/authority
Resolved effective authority.
Requires delegation:read.
#POST /v1/agents/bulk
Bulk lifecycle operation with per-agent results.
Requires agent:revoke. Step-up authentication is also required.
Request body:
json{
"agent_ids": "string[]",
"operation": "pause|resume|suspend|revoke",
"reason": "string"
}
#POST /v1/agents/bulk/preview
Preview a bulk operation before confirming.
Requires agent:read.