Robots Center Agents Network
Log in Create workspace
Skip to content

API reference

Operator - Security

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/security Web Session

Get security overview

Description

Returns workspace security posture including violation counts, service-agent role coverage, installed policy packs, and latest report freshness. Operator routes require a browser session; machine bearer tokens are refused with 401. Session RBAC: owner, admin, and auditor can view; owner and admin can manage. Members receive 403 after the session plug. Reports are treated as stale after 30 days (overview.stale_frameworks).

Auth

Web Session
Responses
200

Security overview
Response Body
Field Type Required Description
agent_roles object Yes Role coverage summary
compliance_status string Yes healthy or attention
latest_reports object Yes Latest SOC 2/GDPR snapshots
policy_pack_installations integer Yes Installed policy pack count
stale_frameworks array<object> Yes Frameworks whose latest report is older than 30 days
violations object Yes Violation summary
401

An authenticated operator session is required
403

Membership cannot view security (owner, admin, or auditor required)
GET
/api/v1/operator/security/violations Web Session

List security violations

Description

Returns filtered policy violations for the current workspace. Filters are nested only: filter[status], filter[severity], filter[violation_type], filter[service_agent_id], and filter[connector_id]. A top-level ?status= is ignored.

Auth

Web Session
Parameters
Name In Type Required Description
filter[status] query string No Filter by status
filter[severity] query string No Filter by severity
filter[violation_type] query string No Filter by violation type
filter[service_agent_id] query string No Service-agent UUID
filter[connector_id] query string No Connector UUID
Responses
200

Security violations
Response Body
Field Type Required Description
violations array<object> Yes Violation list (id, violation_type, severity, status, title, summary, details, detected_at, resolved_at, nested service_agent, connector, audit_event, resolved_by_user)
400

Invalid nested filter value (e.g. invalid_status)
401

An authenticated operator session is required
POST
/api/v1/operator/security/violations/:id/resolve Web Session

Resolve security violation

Description

Marks a security violation as resolved for the current workspace. Owner or admin membership required.

Auth

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

Violation resolved
401

An authenticated operator session is required
403

Owner or admin membership is required
404

Violation not found
409

Violation has already been resolved
GET
/api/v1/operator/security/agents Web Session

List service-agent security posture

Description

Returns service agents with assigned security roles and effective permission summaries.

Auth

Web Session
Responses
200

Service-agent security posture
Response Body
Field Type Required Description
service_agents array<object> Yes Agent security rows
401

An authenticated operator session is required
POST
/api/v1/operator/security/agents/:id/role Web Session

Update service-agent security role

Description

Assigns the fixed security role for a service agent. Owner or admin membership required.

Auth

Web Session
Request Body
Field Type Required Description
agent object Yes Role assignment payload
agent.security_role string Yes admin, operator, or agent
Parameters
Name In Type Required Description
id path string Yes Service agent UUID
Responses
200

Service-agent role updated
401

An authenticated operator session is required
403

Owner or admin membership is required
404

Service agent not found
GET
/api/v1/operator/security/reports Web Session

List compliance reports

Description

Returns SOC 2 and GDPR report snapshots for the current workspace. Optional filter[framework]=soc2|gdpr.

Auth

Web Session
Parameters
Name In Type Required Description
filter[framework] query string No Filter by compliance framework
Responses
200

Compliance reports
Response Body
Field Type Required Description
reports array<object> Yes Report list (id, framework, status, period_start, period_end, summary, sections, generated_at, generated_by_user)
401

An authenticated operator session is required
GET
/api/v1/operator/security/reports/:id Web Session

Get compliance report

Description

Returns a persisted compliance report snapshot.

Auth

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

Compliance report
401

An authenticated operator session is required
404

Compliance report not found
POST
/api/v1/operator/security/reports Web Session

Generate compliance report

Description

Generates and persists a SOC 2 or GDPR audit-prep snapshot from audit events. Omitted dates default to the last 30 days. Windows over 365 days, an invalid framework, or an inverted period return 422.

Auth

Web Session
Request Body
Field Type Required Description
report object Yes Compliance report request
report.framework string Yes soc2 or gdpr
report.period_end datetime (ISO 8601) No Inclusive report window end. Defaults to now.
report.period_start datetime (ISO 8601) No Inclusive report window start. Defaults to 30 days before period_end.
Responses
201

Compliance report generated
401

An authenticated operator session is required
403

Owner or admin membership is required
422

invalid_framework, invalid_period, or report_window_too_large (max 365 days)