Reference
Agents
Admin agent management, runtime token lifecycle, and agent invoke APIs.
Endpoint Map
Admin Management (/api/v1/admin/agents)
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /api/v1/admin/agents | JWT + agent:create | Create agent and return one-time runtime token |
GET | /api/v1/admin/agents | JWT + agent:read | List agents |
GET | /api/v1/admin/agents/:id | JWT + agent:read | Get agent details |
PUT | /api/v1/admin/agents/:id | JWT + agent:update:own or agent:update:all | Update agent |
DELETE | /api/v1/admin/agents/:id | JWT + delete permission | Delete agent |
POST | /api/v1/admin/agents/:id/disable | JWT + update permission | Kill-switch disable |
POST | /api/v1/admin/agents/:id/enable | JWT + update permission | Re-enable |
POST | /api/v1/admin/agents/:id/regenerate-token | JWT + update permission | Rotate runtime token |
Runtime/User Routes (/api/v1/agents)
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /api/v1/agents/:agentId/invoke | Flexible auth | Invoke upstream agent runtime |
GET | /api/v1/agents/:agentId/credentials-check | Flexible auth | Pre-check required credentials |
GET | /api/v1/agents/:agentId | Flexible auth | Get public agent info |
Create Agent
POST /api/v1/admin/agents
Authorization: Bearer <jwt>
Content-Type: application/json
{
"name": "Finance Bot",
"upstreamUrl": "https://finance-agent.internal/mcp",
"requiredCredentials": [{ "serviceType": "gateway_api" }],
"description": "Handles financial queries"
}{
"success": true,
"agent": {
"id": "agt_...",
"name": "Finance Bot",
"upstreamUrl": "https://finance-agent.internal/mcp",
"hasUpstreamSecret": false,
"isActive": true,
"requireConfirmation": false,
"requiredCredentials": [{ "serviceType": "gateway_api" }],
"runtimeTokenPrefix": "art_xxxx",
"createdAt": "2026-03-07T12:00:00.000Z"
},
"runtime_token": "art_..."
}runtime_token plaintext is only returned on create/rotate.
Invoke Agent
POST /api/v1/agents/:agentId/invoke
Authorization: Bearer <user-jwt>
Content-Type: application/json
{
"message": "Show me all agents"
}If credentials are missing:
{
"code": "CREDENTIALS_REQUIRED",
"missing": ["gateway_api"],
"authUrls": {
"gateway_api": "/auth/connect?service=gateway_api"
},
"message": "Authentication required for: gateway_api"
}On success, response is JSON-wrapped ({ success, request_id, data }) or forwarded SSE stream.
Credentials Pre-check
GET /api/v1/agents/:agentId/credentials-check
Authorization: Bearer <user-jwt>Returns { ok: true } when all required credentials are present; otherwise 401 with CREDENTIALS_REQUIRED payload.