# Commands

> The Commands operations of the Hub REST API (3 operations).

URL: https://docs.synap.live/docs/reference/hub-api/commands · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /commands

List commands available to the user

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `workspaceId` | query | string |  |  |

Responses:

- `200`: Commands
- `403`: Forbidden
- `500`: Internal error

## GET /commands/{id}

Get a single command

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

Responses:

- `200`: Command
- `403`: Forbidden
- `404`: Command not found
- `500`: Internal error

## POST /commands/execute

Execute a command (RBAC + proposal flow)

Runs a shell-compatible command after security gating. Three terminal states: `executed`, `proposed` (awaiting approval), `denied` (blocked by policy). Rate-limited to 10/min per workspace.

Request body (`application/json`): ExecuteCommandRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `command` | string | yes | Shell-compatible command line. Subject to BLOCKED_COMMAND_PATTERNS. |
| `workingDir` | string |  | Optional working directory. Path traversal and sensitive system dirs are rejected. |
| `timeoutMs` | number |  | Defaults to 30s. Hard-capped at 5 minutes. |
| `userId` | string |  |  |
| `workspaceId` | string |  | Workspace context. When set, rate-limit (10/min) applies and an event is emitted on completion. |
| `agentUserId` | string |  |  |
| `sourceMessageId` | string |  |  |
| `reason` | string |  | Human-readable reason — included in proposal payload when one is created. |

Responses:

- `200`: Execution result, proposal, or denial
- `400`: Bad request
- `403`: Forbidden
- `429`: Rate limit exceeded
- `500`: Internal error