Agent: Permissions

Download Page (.md)

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.

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

curl https://api.hoody.com/api/v1/workspaces/wks_abc123/config/permission \
  -H "Authorization: Bearer &lt;token&gt;"

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.

[
  {
    "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

cURL
TypeScript SDK

curl https://api.hoody.com/api/v1/workspaces/wks_abc123/permissions \
  -H "Authorization: Bearer &lt;token&gt;"

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.

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

Response

Permission processed successfully. Returns a boolean indicating success.

true

The reply payload is invalid or missing required fields.

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

The permission request could not be found.

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

Example request

cURL
TypeScript SDK

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

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