# Agent: Permissions

**Page:** api/agent/permissions

[Download Raw Markdown](./api/agent/permissions.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Agent Permissions API lets you list pending permission requests, respond to permission prompts, and inspect per-tool permission overrides. Use these endpoints to programmatically manage how the AI agent requests and receives authorization for actions such as file edits, shell commands, and web fetches within a workspace.

## Get workspace permission overrides

### `GET /api/v1/workspaces/{workspaceID}/config/permission`

Get permission and yolo overrides from the workspace config only (not merged with global).

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |

### Response




Returns the workspace-level permission and yolo overrides.

```json
{
  "permission": {
    "edit": "allow",
    "bash": "ask",
    "webfetch": "allow"
  },
  "yolo": false,
  "tool_wake_policy": {
    "webfetch": "auto",
    "bash": "next_turn"
  }
}
```




### Example request



```bash
curl https://api.hoody.com/api/v1/workspaces/wks_abc123/config/permission \
  -H "Authorization: Bearer <token>"
```


```typescript
const overrides = await client.agent.permissions.getOverrides({
  workspaceID: "wks_abc123"
});
```



## List pending permissions

### `GET /api/v1/workspaces/{workspaceID}/permissions`

Get all pending permission requests across all sessions in the workspace.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |

### Response




Returns an array of pending permission requests.

```json
[
  {
    "id": "per_abc123def456",
    "sessionID": "507f1f77bcf86cd799439011",
    "permission": "edit",
    "patterns": ["*.ts", "*.tsx"],
    "metadata": {
      "filepath": "/home/user/project/src/index.ts"
    },
    "always": [],
    "tool": {
      "messageID": "msg_xyz789",
      "callID": "call_456abc"
    }
  },
  {
    "id": "per_def456ghi789",
    "sessionID": "507f1f77bcf86cd799439012",
    "permission": "bash",
    "patterns": ["rm -rf *", "sudo *"],
    "metadata": {
      "command": "sudo systemctl restart nginx"
    },
    "always": ["npm install *"]
  }
]
```




### Example request



```bash
curl https://api.hoody.com/api/v1/workspaces/wks_abc123/permissions \
  -H "Authorization: Bearer <token>"
```


```typescript
const pending = await client.agent.permissions.list({
  workspaceID: "wks_abc123"
});
```



## Respond to permission request

### `POST /api/v1/workspaces/{workspaceID}/permissions/{requestID}/reply`

Approve or deny a permission request from the AI assistant.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `requestID` | path | string | Yes | The permission request identifier |

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `reply` | string | Yes | The decision for this request. One of `once`, `always`, or `reject`. |
| `message` | string | No | An optional message accompanying the decision. |

```json
{
  "reply": "once",
  "message": "Approved for this edit only"
}
```

### Response




Permission processed successfully. Returns a boolean indicating success.

```json
true
```




The reply payload is invalid or missing required fields.

```json
{
  "data": {},
  "errors": [
    {
      "code": "INVALID_REPLY",
      "message": "reply must be one of: once, always, reject"
    }
  ],
  "success": false
}
```




The permission request could not be found.

```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Permission request per_abc123 not found"
  }
}
```




### Example request



```bash
curl -X POST https://api.hoody.com/api/v1/workspaces/wks_abc123/permissions/per_abc123def456/reply \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reply": "once", "message": "Approved for this edit only"}'
```


```typescript
const result = await client.agent.permissions.reply({
  workspaceID: "wks_abc123",
  requestID: "per_abc123def456",
  data: {
    reply: "once",
    message: "Approved for this edit only"
  }
});
```