Operator - Gateway API Reference

GET

/api/v1/operator/connector_templates Web Session

List connector catalog entries

Description

Returns built-in connector catalog entries with setup recipes, auth field schemas, supported environments, and linked policy template packs.

Auth

Web Session

Responses

200

List of connector catalog entries

Returns: ConnectorTemplateList

GET

/api/v1/operator/connectors Web Session

List connectors

Description

Returns all connectors in the current workspace, including active and paused connectors.

Auth

Web Session

Responses

200

List of connectors

Returns: ConnectorList

POST

/api/v1/operator/connectors Web Session

Create connector

Description

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

Auth

Web Session

Request Body

Field	Type	Required	Description
name	string	Yes	Connector display name
status	string (active, paused)	No	Initial status
config	object	No	Connector-specific configuration
description	string	No	Connector description
category	string	No	Connector category (e.g., 'email', 'custom')
slug	string	No	URL-safe slug (auto-generated from name if omitted)

Responses

201

Connector created

Returns: Connector

422

Validation error

GET

/api/v1/operator/connectors/:id Web Session

Get connector details

Description

Returns details of a specific connector.

Auth

Web Session

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Connector UUID

Responses

200

Connector details

Returns: Connector

404

Connector not found

PATCH

/api/v1/operator/connectors/:id Web Session

Update connector

Description

Updates a connector's configuration. Accepts either top-level fields or a 'connector' wrapper key.

Auth

Web Session

Request Body

Field	Type	Required	Description
name	string	No	Connector display name
status	string (active, paused)	No	Connector status
config	object	No	Connector-specific configuration
description	string	No	Connector description
category	string	No	Connector category

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Connector UUID

Responses

200

Connector updated

Returns: Connector

404

Connector not found

DELETE

/api/v1/operator/connectors/:id Web Session

Delete (archive) connector

Description

Archives a connector. The connector is soft-deleted by setting archived_at. Archived connectors are excluded from gateway authorization checks.

Auth

Web Session

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Connector UUID

Responses

200

Connector archived

Returns: Connector

404

Connector not found

GET

/api/v1/operator/policy_template_packs Web Session

List policy template packs

Description

Returns built-in policy packs plus installation state for the current workspace.

Auth

Web Session

Responses

200

List of policy template packs

Returns: PolicyTemplatePackList

POST

/api/v1/operator/policy_template_packs Web Session

Create policy template pack

Description

Creates a new custom policy template pack in the current workspace. Requires workspace admin privileges.

Auth

Web Session

Request Body

Field	Type	Required	Description
name	string	Yes	Policy pack name
status	string (draft, published, archived)	No	Pack status
version	string	No	Pack version (default: '1.0.0')
description	string	No	Policy pack description
category	string	No	Policy pack category
connectors	object	No	Connector definitions linked to this pack
grants	object	No	Permission grant rules
policies	object	No	Policy rule definitions

Responses

201

Policy template pack created

Returns: PolicyTemplatePack

422

Validation error

POST

/api/v1/operator/policy_template_packs/:id/install Web Session

Install a policy template pack

Description

Installs a built-in policy pack into the current workspace. Installs are idempotent per pack version.

Auth

Web Session

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Policy pack identifier

Responses

201

Policy template pack installed

Returns: PolicyTemplatePackInstallation

404

Policy template pack not found

GET

/api/v1/operator/managed_secrets Web Session

List managed secrets

Description

Returns workspace-managed secret references used by workflow targets and other operator-configured integrations.

Auth

Web Session

Responses

200

List of managed secrets

Returns: ManagedSecretList

POST

/api/v1/operator/managed_secrets Web Session

Create a managed secret

Description

Stores a managed secret through the configured provider and returns a workspace-scoped reference record.

Auth

Web Session

Request Body

Field	Type	Required	Description
name	string	Yes	Display name for the secret
value	string	Yes	Plaintext secret value
slug	string	No	Optional URL-safe secret slug
provider_key	string	No	Optional provider-side storage key
purpose	string	No	Operator-defined purpose label

Responses

201

Managed secret created

Returns: ManagedSecret

422

Invalid managed secret payload

POST

/api/v1/operator/managed_secrets/:id/rotate Web Session

Rotate a managed secret

Description

Rotates the underlying provider value for a managed secret and increments its recorded version.

Auth

Web Session

Request Body

Field	Type	Required	Description
value	string	Yes	Replacement plaintext value

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Managed secret UUID

Responses

200

Managed secret rotated

Returns: ManagedSecret

404

Managed secret not found

422

Invalid rotation payload

POST

/api/v1/operator/policy_simulations Web Session

Simulate a gateway policy decision

Description

Runs a dry-run authorization decision with condition explanations.

Auth

Web Session

Request Body

Field	Type	Required	Description
simulation	object	Yes	Simulation payload

Responses

200

Simulation result

404

Connector not found

GET

/api/v1/operator/gateway_freezes Web Session

List gateway freezes

Description

Returns gateway freezes newest first, active and historical. Always bounded: `limit` defaults to 25 and is clamped to 100. Each entry carries `active`, which is false once the freeze is lifted *or* once its `expires_at` has passed, even if the expiry sweeper has not stamped it yet.

Auth

Web Session

Parameters

Name	In	Type	Required	Description
status	query	string	No	Filter to freezes still in force, or to lifted ones
limit	query	integer	No	Maximum freezes to return (default 25, server maximum 100)

Responses

200

List of gateway freezes

Returns: GatewayFreezeList

Example

{
  "gateway_freezes": [
    {
      "active": true,
      "connector_id": null,
      "created_by": {
        "email": "[email protected]",
        "id": "0d4a5c9b-2c31-4a1e-9c5d-7f2a1b8e3c40"
      },
      "expires_at": "2026-08-03T23:15:00Z",
      "id": "6b2f0f4c-8a1e-4a2e-9c1f-2f0a6b0d51e2",
      "inserted_at": "2026-08-03T21:15:00Z",
      "lift_kind": null,
      "lifted_at": null,
      "lifted_by": null,
      "reason": "agent X issuing runaway commands",
      "scope_type": "workspace",
      "service_agent_id": null,
      "updated_at": "2026-08-03T21:15:00Z",
      "workspace_id": "6f2a5f4b-9c34-4c8e-9f1a-1a2b3c4d5e6f"
    }
  ]
}

POST

/api/v1/operator/gateway_freezes Web Session

Freeze the gateway

Description

Stops gateway execution immediately for the whole workspace, one connector, or one service agent. A `reason` is required. A workspace freeze also refuses machine authentication: API requests and agent socket connects for the workspace answer `403` with `"error": "workspace_frozen"` while it is in force. Connector and service-agent freezes are narrower — the credential still authenticates, but every authorization decision for that scope is denied with `decision_path: "frozen"`. Freezing a scope that is already frozen returns the freeze already in force rather than stacking a second one, so two responders hitting the same button do not fragment the audit trail. Requires an owner or admin membership.

Auth

Web Session

Request Body

Field	Type	Required	Description
reason	string	Yes	Why the gateway is being stopped (3-2000 characters)
expires_at	string	No	Optional automatic thaw time (ISO 8601, must be in the future)
service_agent_id	string	No	Service agent UUID; required when scope_type is "service_agent"
connector_id	string	No	Connector UUID; required when scope_type is "connector"
scope_type	string (workspace, connector, service_agent)	Yes	What the freeze covers

Responses

201

Freeze in force

Returns: GatewayFreeze

Example

{
  "active": true,
  "connector_id": null,
  "created_by": {
    "email": "[email protected]",
    "id": "0d4a5c9b-2c31-4a1e-9c5d-7f2a1b8e3c40"
  },
  "expires_at": "2026-08-03T23:15:00Z",
  "id": "6b2f0f4c-8a1e-4a2e-9c1f-2f0a6b0d51e2",
  "inserted_at": "2026-08-03T21:15:00Z",
  "lift_kind": null,
  "lifted_at": null,
  "lifted_by": null,
  "reason": "agent X issuing runaway commands",
  "scope_type": "workspace",
  "service_agent_id": null,
  "updated_at": "2026-08-03T21:15:00Z",
  "workspace_id": "6f2a5f4b-9c34-4c8e-9f1a-1a2b3c4d5e6f"
}

403

An owner or admin membership is required

422

Missing reason, or a scope target that does not match scope_type

POST

/api/v1/operator/gateway_freezes/:id/lift Web Session

Lift a gateway freeze

Description

Ends a freeze and records who lifted it with `lift_kind: "manual"`. A freeze whose expiry has already passed but which the sweeper has not reached yet is still liftable and is recorded as a manual lift. Requires an owner or admin membership.

Auth

Web Session

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Gateway freeze UUID

Responses

200

Freeze lifted

Returns: GatewayFreeze

Example

{
  "active": false,
  "connector_id": null,
  "created_by": {
    "email": "[email protected]",
    "id": "0d4a5c9b-2c31-4a1e-9c5d-7f2a1b8e3c40"
  },
  "expires_at": "2026-08-03T23:15:00Z",
  "id": "6b2f0f4c-8a1e-4a2e-9c1f-2f0a6b0d51e2",
  "inserted_at": "2026-08-03T21:15:00Z",
  "lift_kind": "manual",
  "lifted_at": "2026-08-03T22:02:00Z",
  "lifted_by": {
    "email": "[email protected]",
    "id": "0d4a5c9b-2c31-4a1e-9c5d-7f2a1b8e3c40"
  },
  "reason": "agent X issuing runaway commands",
  "scope_type": "workspace",
  "service_agent_id": null,
  "updated_at": "2026-08-03T21:15:00Z",
  "workspace_id": "6f2a5f4b-9c34-4c8e-9f1a-1a2b3c4d5e6f"
}

403

An owner or admin membership is required

404

Freeze not found

409

This freeze has already been lifted

Operator - Gateway

Endpoints

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Description

Auth

Example

Description

Auth

Example

Description

Auth

Example