Permissions API

Permissions define which tool operations agents can execute autonomously. Patterns use glob-style matching against tool names. Presets bundle commonly needed patterns into one-click configurations.

Quick Start

List current permissions, add a new pattern, and enable a preset — a typical setup flow:

// 1. List currently allowed permission patterns
const res1: Response = await fetch('/api/permissions');
const { permissions }: { permissions: string[] } = await res1.json();
console.log(`${permissions.length} patterns allowed`);
permissions.forEach((p: string) => console.log(`  ${p}`));

// 2. Add a new permission pattern for git commands
await fetch('/api/permissions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ pattern: 'Bash(git *)' }),
});

// 3. Browse available presets and enable one
const res2: Response = await fetch('/api/permissions/presets');
const { presets }: { presets: Array<{ id: string; name: string; patterns: string[] }> } = await res2.json();
const devTools = presets.find((p) => p.id === 'developer-tools')!;
console.log(`${devTools.name}: ${devTools.patterns.length} patterns`);

await fetch('/api/permissions/presets', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ presetId: 'developer-tools' }),
});

// 4. Verify — the preset's patterns are now in the allow list
const res3: Response = await fetch('/api/permissions');
const updated: { permissions: string[] } = await res3.json();
console.log(`Now ${updated.permissions.length} patterns allowed`);

import requests

# 1. List currently allowed permission patterns
res1: requests.Response = requests.get("http://localhost:3000/api/permissions")
data: dict = res1.json()
print(f"{len(data['permissions'])} patterns allowed")
for p in data["permissions"]:
  print(f"  {p}")

# 2. Add a new permission pattern for git commands
requests.post(
  "http://localhost:3000/api/permissions",
  json={"pattern": "Bash(git *)"},
)

# 3. Browse available presets and enable one
res2: requests.Response = requests.get("http://localhost:3000/api/permissions/presets")
presets: list[dict] = res2.json()["presets"]
dev_tools: dict = next(p for p in presets if p["id"] == "developer-tools")
print(f"{dev_tools['name']}: {len(dev_tools['patterns'])} patterns")

requests.post(
  "http://localhost:3000/api/permissions/presets",
  json={"presetId": "developer-tools"},
)

# 4. Verify — the preset's patterns are now in the allow list
res3: requests.Response = requests.get("http://localhost:3000/api/permissions")
updated: dict = res3.json()
print(f"Now {len(updated['permissions'])} patterns allowed")

Base URL

/api/permissions

Endpoints

List Allowed Permissions

GET /api/permissions

Retrieve all currently allowed permission patterns.

Response Body

Field	Type	Req	Description
permissions	string[]	*	Array of glob patterns for allowed tool operations

Fetch the current allow list to audit what agents can do without asking:

// Audit the current permission allow list
const res: Response = await fetch('http://localhost:3000/api/permissions');
const { permissions }: { permissions: string[] } = await res.json();

console.log(`${permissions.length} permission patterns:`);
permissions.forEach((p: string) => console.log(`  ${p}`));

import requests

# Audit the current permission allow list
res: requests.Response = requests.get("http://localhost:3000/api/permissions")
data: dict = res.json()

print(f"{len(data['permissions'])} permission patterns:")
for p in data["permissions"]:
  print(f"  {p}")

Example response:

{
  "permissions": [
    "Read(*)",
    "Bash(git *)",
    "Bash(npm test)",
    "Write(src/**)"
  ]
}

Add Permission Pattern

POST /api/permissions

Add a new tool permission pattern to the allow list.

Request Body

Field	Type	Req	Description
pattern	string	*	Glob pattern to allow (e.g., "Bash()", "Read()")

Response 200 — { "success": true }

Add a permission so agents can run git commands without needing approval each time:

// Allow agents to run git commands autonomously
await fetch('http://localhost:3000/api/permissions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ pattern: 'Bash(git *)' }),
});

import requests

# Allow agents to run git commands autonomously
requests.post(
  "http://localhost:3000/api/permissions",
  json={"pattern": "Bash(git *)"},
)

Errors: 400 — Pattern is required

Remove Permission Pattern

DELETE /api/permissions

Remove a tool permission pattern from the allow list.

Request Body

Field	Type	Req	Description
pattern	string	*	Exact pattern to remove

Response 200 — { "success": true }

Revoke a permission when you want agents to ask for approval again:

// Revoke git permission — agents will need approval again
await fetch('http://localhost:3000/api/permissions', {
method: 'DELETE',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ pattern: 'Bash(git *)' }),
});

import requests

# Revoke git permission — agents will need approval again
requests.delete(
  "http://localhost:3000/api/permissions",
  json={"pattern": "Bash(git *)"},
)

Errors: 400 — Pattern is required

Permission Presets

List Presets

GET /api/permissions/presets

List all available permission presets with their current active status.

Response Body

Field	Type	Req	Description
presets	object[]	*	Array of preset objects
presets[].id	string	*	Preset identifier
presets[].name	string	*	Human-readable preset name
presets[].description	string	*	What this preset enables
presets[].patterns	string[]	*	Permission patterns included in this preset
presets[].active	boolean	*	Whether this preset is currently enabled

Browse presets to see what bundles are available and which are already active:

// List presets and show which are active
const res: Response = await fetch('http://localhost:3000/api/permissions/presets');
const { presets }: { presets: Array<{ name: string; description: string; patterns: string[]; active: boolean }> } = await res.json();

presets.forEach((p) => {
const status: string = p.active ? 'ACTIVE' : 'inactive';
console.log(`[${status}] ${p.name} — ${p.description}`);
p.patterns.forEach((pat: string) => console.log(`    ${pat}`));
});

import requests

# List presets and show which are active
res: requests.Response = requests.get("http://localhost:3000/api/permissions/presets")
data: dict = res.json()

for p in data["presets"]:
  status: str = "ACTIVE" if p["active"] else "inactive"
  print(f"[{status}] {p['name']} — {p['description']}")
  for pat in p["patterns"]:
      print(f"    {pat}")

Example response:

{
  "presets": [
    {
      "id": "developer-tools",
      "name": "Developer Tools",
      "description": "Read files, run git commands, execute tests",
      "patterns": ["Read(*)", "Bash(git *)", "Bash(npm test)", "Bash(npm run *)"],
      "active": true
    },
    {
      "id": "file-writer",
      "name": "File Writer",
      "description": "Write and edit files in the project directory",
      "patterns": ["Write(src/**)", "Write(docs/**)"],
      "active": false
    }
  ]
}

Enable Preset

POST /api/permissions/presets

Activate a preset, adding all its permission patterns to the allow list.

Request Body

Field	Type	Req	Description
presetId	string	*	Preset identifier to enable

Response 200 — { "success": true }

Enable a preset to grant a bundle of permissions at once:

// Enable the developer-tools preset
await fetch('http://localhost:3000/api/permissions/presets', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ presetId: 'developer-tools' }),
});

import requests

# Enable the developer-tools preset
requests.post(
  "http://localhost:3000/api/permissions/presets",
  json={"presetId": "developer-tools"},
)

Errors: 400 — presetId required, 404 — Unknown preset

Disable Preset

DELETE /api/permissions/presets

Deactivate a preset, removing its unique permission patterns from the allow list.

Request Body

Field	Type	Req	Description
presetId	string	*	Preset identifier to disable

Response 200 — { "success": true }

Disable a preset to revoke its patterns — only removes patterns unique to the preset:

// Disable the developer-tools preset
await fetch('http://localhost:3000/api/permissions/presets', {
method: 'DELETE',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ presetId: 'developer-tools' }),
});

import requests

# Disable the developer-tools preset
requests.delete(
  "http://localhost:3000/api/permissions/presets",
  json={"presetId": "developer-tools"},
)

Errors: 400 — presetId required, 404 — Unknown preset

Pattern Syntax

Permission patterns use glob-style matching against tool invocation strings:

Pattern	Matches
`Bash(*)`	Any Bash command
`Bash(git *)`	Git commands only
`Read(*)`	Any file read
`Write(*)`	Any file write
`mcp__*`	Any MCP tool invocation