---
title: "Register a machine actor"
method: POST
path: "/agents/register"
tags: ["agents"]
---

# Register a machine actor

`POST /agents/register`

## Request

- Base URL: `https://catalyst.stratogenic.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://catalyst.stratogenic.ai/agents/register`
- Auth: API key in header `X-API-Key`

Register an AI agent, Zapier Zap, n8n workflow, or other automated actor that will take actions on behalf of a tenant.

Every actor that touches Catalyst state should be registered here. The `machine_actor_id` links ledger entries and proposals to the responsible actor, making the audit trail queryable by actor.

Gated on `can_configure_ai_workflows`.

## Headers

- `X-User-Id` string, nullable

## Request body

- ActorRegistration
  - `machine_actor_id` string, nullable: Caller-supplied ID; auto-generated if omitted
  - `display_name` string, required
  - `runtime_type` string: One of: claude_agent, custom_agent, internal_worker, make_scenario, n8n_workflow, openai_assistant, unknown, zapier_zap
  - `owner_group` string, nullable
  - `capabilities` string[]: Declared capabilities this actor may exercise
  - `scopes` string[]: API scopes permitted
  - `risk_class` 'low' | 'standard' | 'high'
  - `governance_mode` 'observe' | 'advisory' | 'proposal' | 'strict'
  - `notes` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `403`: Plan does not allow registering machine actors.
- `409`: An actor with this ID is already registered for this tenant.
- `422`: Validation Error

---

[API](https://skmtc.dev/stratogenic/apis/stratogenic-catalyst-api.md) · [All operations](https://skmtc.dev/stratogenic/apis/stratogenic-catalyst-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stratogenic/apis/stratogenic-catalyst-api/revisions/ad906ad7a85d?raw)