Robots Center Agents Network
Log in Create workspace
Skip to content

API reference

Operator - Service Agents

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

8
GET
/api/v1/operator/agent_enrollments Web Session

List agent enrollments

Description

Lists enrollment history for the active workspace without exposing token secrets. Owner or admin membership is required, matching create and revoke.

Auth

Web Session
Responses
200

Agent enrollment history
403

Owner or admin membership required
POST
/api/v1/operator/agent_enrollments Web Session

Create an agent or fleet enrollment token

Description

Creates a short-lived enrollment token. A single-use token (`max_claims` of 1, the default) also creates the canonical service-agent identity, and robot enrollments create and link the robot record. A fleet claim token (`max_claims` > 1) creates no identity up front — each claim mints its own. Owner or admin membership is required. The same mint/revoke surface is /app/agents/enrollments in the operator console.

Auth

Web Session
Request Body
Field Type Required Description
enrollment object Yes Agent or robot enrollment attributes
enrollment.name string Yes Agent or robot name
enrollment.kind string (agent, robot) No Enrollment kind
enrollment.scopes array<object> No Explicit scopes overriding the preset
enrollment.cohort_id string No Cohort every claimed unit joins. Cleared if the cohort is deleted.
enrollment.serial_number string No Required for robot enrollments
enrollment.robot_type string (amr, drone, manipulator, humanoid) No Robot type
enrollment.default_tags array<object> No Tags applied to every claimed unit (lowercased and trimmed)
enrollment.expires_in_minutes integer No Token lifetime from 5 to 1440 minutes
enrollment.max_claims integer No How many times the token may be claimed (1 to 1000, default 1). Above 1 the token becomes a fleet claim token.
enrollment.scope_preset string (read_only, worker, robot) No Minimal preconfigured scope set
enrollment.serial_allowlist array<object> No Serial numbers permitted to claim this token. Empty means any serial is accepted.
Responses
201

Enrollment created; token returned once
400

cohort_id is not a cohort in this workspace (detail invalid_cohort). Problem JSON via FallbackController.
403

Owner or admin membership required
422

Validation error
429

Plan agent or robot quota reached while creating the single-use identity (type problems/quota-exceeded). Fleet claim tokens (max_claims > 1) do not create an identity up front and do not hit this gate on create.
DELETE
/api/v1/operator/agent_enrollments/:id Web Session

Revoke an active enrollment

Description

Invalidates an enrollment token that has not been used up.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Enrollment UUID
Responses
200

Enrollment revoked
404

Enrollment not found
409

Enrollment is no longer active
GET
/api/v1/operator/service_agents Web Session

List service agents

Description

Returns all service agents in the current workspace.

Auth

Web Session
Parameters
Name In Type Required Description
query query string No Search name, slug, framework, or agent type
status query string No Filter by lifecycle status
availability query string No Filter by runtime availability
Responses
200

List of service agents
Response Body
Field Type Required Description
service_agents array<object> Yes Array of service agents
service_agents[].id string Yes Service agent UUID
service_agents[].name string Yes Service agent name
service_agents[].status string (active, paused, revoked) Yes Current status
service_agents[].description string No Description
service_agents[].metadata object No Arbitrary metadata
service_agents[].inserted_at datetime (ISO 8601) Yes Creation time
service_agents[].updated_at datetime (ISO 8601) Yes Last update time
service_agents[].slug string Yes URL-safe slug
service_agents[].archived_at datetime (ISO 8601) No Archive timestamp
service_agents[].last_token_issued_at datetime (ISO 8601) No Last API key issuance time
service_agents[].security_role string (admin, operator, agent) Yes Security role for gateway authorization
Example
{
  "service_agents": [
    {
      "description": "Handles payment processing workflows",
      "id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
      "inserted_at": "2026-02-01T08:00:00Z",
      "name": "payments-agent",
      "slug": "payments-agent",
      "status": "active",
      "updated_at": "2026-03-27T09:00:00Z",
      "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
    }
  ]
}
POST
/api/v1/operator/service_agents Web Session

Create service agent

Description

Creates a new service agent in the current workspace. The slug is auto-generated from the name if not provided.

Auth

Web Session
Request Body
Field Type Required Description
service_agent object Yes Service agent attributes
service_agent.name string Yes Service agent name (2-120 characters)
service_agent.status string (active, paused, revoked) No Initial status
service_agent.description string No Service agent description
service_agent.metadata object No Arbitrary metadata key-value pairs
service_agent.slug string No URL-safe slug (auto-generated from name if omitted)
service_agent.security_role string (admin, operator, agent) No Security role for gateway authorization (defaults to 'agent')
Responses
201

Service agent created

Returns: ServiceAgent
Example
{
  "description": "Handles payment processing workflows",
  "id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
  "inserted_at": "2026-02-01T08:00:00Z",
  "name": "payments-agent",
  "slug": "payments-agent",
  "status": "active",
  "updated_at": "2026-03-27T09:00:00Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}
422

Validation error
GET
/api/v1/operator/service_agents/:id Web Session

Get service agent details

Description

Returns details of a specific service agent.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Service agent UUID
Responses
200

Service agent details
Response Body
Field Type Required Description
id string Yes Service agent UUID
name string Yes Service agent name
status string (active, paused, revoked) Yes Current status
description string No Description
metadata object No Arbitrary metadata
inserted_at datetime (ISO 8601) Yes Creation time
updated_at datetime (ISO 8601) Yes Last update time
slug string Yes URL-safe slug
archived_at datetime (ISO 8601) No Archive timestamp
last_token_issued_at datetime (ISO 8601) No Last API key issuance time
security_role string (admin, operator, agent) Yes Security role for gateway authorization
Example
{
  "description": "Handles payment processing workflows",
  "id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
  "inserted_at": "2026-02-01T08:00:00Z",
  "name": "payments-agent",
  "slug": "payments-agent",
  "status": "active",
  "updated_at": "2026-03-27T09:00:00Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}
404

Service agent not found
PATCH
/api/v1/operator/service_agents/:id Web Session

Update service agent

Description

Updates a service agent's configuration.

Auth

Web Session
Request Body
Field Type Required Description
service_agent object Yes Service agent attributes to update
service_agent.name string No Service agent name
service_agent.status string (active, paused, revoked) No Service agent lifecycle status
service_agent.description string No Service agent description
Parameters
Name In Type Required Description
id path string Yes Service agent UUID
Responses
200

Service agent updated

Returns: ServiceAgent
Example
{
  "description": "Handles payment processing workflows",
  "id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
  "inserted_at": "2026-02-01T08:00:00Z",
  "name": "payments-agent",
  "slug": "payments-agent",
  "status": "active",
  "updated_at": "2026-03-27T09:00:00Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}
404

Service agent not found
DELETE
/api/v1/operator/service_agents/:id Web Session

Delete service agent

Description

Deletes a service agent and revokes all its credentials.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Service agent UUID
Responses
204

Service agent deleted
404

Service agent not found