Settings

Endpoints for managing team-specific AI configuration.

GET /api/ai-team-settings/{teamId}

Get AI settings for a specific team.

Authentication: permission.team.manageAi(teamId)

Path Parameters:

Parameter	Type	Description
teamId	string	Team ID

Response:

{
  "teamId": "team-123",
  "settings": {
    "enabled": true,
    "defaultModelId": "claude-3-5-sonnet",
    "allowedModelTiers": ["everyday", "advanced"],
    "allowWeb": true,
    "allowAttachments": true,
    "maxWeeklyBudget": 10.00,
    "maxSessionBudget": 2.00,
    "defaultInstructions": "You are a helpful assistant for the sales team.",
    "allowedToolkits": ["informer", "custom-123"],
    "restrictedDatasets": ["sensitive-data-456"],
    "autoSummarize": true,
    "summarizeInterval": 20
  },
  "createdAt": "2024-01-10T09:00:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

Settings Fields:

Field	Type	Description
enabled	boolean	AI enabled for this team
defaultModelId	string	Default model for new chats
allowedModelTiers	array	Permitted model tiers for team users
allowWeb	boolean	Allow web access in chats
allowAttachments	boolean	Allow file attachments
maxWeeklyBudget	number	Team-wide weekly budget cap (USD)
maxSessionBudget	number	Team-wide session budget cap (USD)
defaultInstructions	string	Default system prompt for team chats
allowedToolkits	array	Toolkit IDs available to team
restrictedDatasets	array	Dataset IDs team cannot access
autoSummarize	boolean	Auto-create memories
summarizeInterval	integer	Messages per auto-summary segment

Use Cases:

• Department-specific AI configuration
• Compliance and security restrictions
• Budget allocation per team
• Custom default settings

Team Hierarchy

Team settings override tenant-level defaults but are superseded by user-specific preferences where applicable.

---

PUT /api/ai-team-settings/{teamId}

Update AI settings for a team.

Authentication: permission.team.manageAi(teamId)

Path Parameters:

Parameter	Type	Description
teamId	string	Team ID

Request Body:

Field	Type	Description
enabled	boolean	Enable/disable AI for team
defaultModelId	string	Default model ID
allowedModelTiers	array	Permitted tiers: everyday, advanced, strategic
allowWeb	boolean	Allow web access
allowAttachments	boolean	Allow file uploads
maxWeeklyBudget	number	Team weekly budget (USD)
maxSessionBudget	number	Team session budget (USD)
defaultInstructions	string	Default system prompt
allowedToolkits	array	Available toolkit IDs
restrictedDatasets	array	Blocked dataset IDs
autoSummarize	boolean	Enable auto-summarization
summarizeInterval	integer	Messages per summary (10-100)

Example Request:

{
  "enabled": true,
  "defaultModelId": "claude-3-5-sonnet",
  "allowedModelTiers": ["everyday", "advanced"],
  "allowWeb": false,
  "maxWeeklyBudget": 15.00,
  "defaultInstructions": "Focus on data analysis and reporting.",
  "autoSummarize": true,
  "summarizeInterval": 25
}

Response:

Returns the updated team settings object.

Validation:

• maxWeeklyBudget must be positive
• maxSessionBudget must be less than maxWeeklyBudget
• summarizeInterval must be between 10 and 100
• defaultModelId must reference an existing model
• allowedToolkits must reference existing toolkits
• restrictedDatasets must reference existing datasets

---

DELETE /api/ai-team-settings/{teamId}

Remove AI settings for a team (reverts to tenant defaults).

Authentication: permission.team.manageAi(teamId)

Path Parameters:

Parameter	Type	Description
teamId	string	Team ID

Response:

204 No Content

Side Effects:

• Team reverts to tenant-level AI configuration
• Existing chats continue using their configured models
• New chats use tenant defaults

---

Team Settings Hierarchy

Settings are resolved in this order (first match wins):

1. User preferences - Individual user overrides
2. Team settings - Team-specific configuration
3. Tenant defaults - System-wide defaults

Example Resolution:

User alice is in team "Sales"

Alice's chat model resolution:
1. Check: alice.preferences.defaultModelId → null (not set)
2. Check: sales_team.settings.defaultModelId → "claude-3-5-sonnet"
3. Use: "claude-3-5-sonnet"

Alice's budget resolution:
1. Check: alice.seat.plan.weeklyBudget → $2.00 (seat-level)
2. Check: sales_team.settings.maxWeeklyBudget → $10.00 (team cap)
3. Use: min($2.00, $10.00) = $2.00

Budget Caps:

Team budget caps apply across all team members:

• Individual user budgets are enforced first
• Team-wide cap applies to aggregate team usage
• If team cap is reached, all team members are restricted
• Boost budgets bypass team caps (admin-granted only)

---

Configuration Best Practices

Tier Restrictions

Restrict tiers based on team function:

{
  "sales_team": {
    "allowedModelTiers": ["everyday", "advanced"]
  },
  "executive_team": {
    "allowedModelTiers": ["advanced", "strategic"]
  },
  "support_team": {
    "allowedModelTiers": ["everyday"]
  }
}

Budget Allocation

Allocate budgets based on expected usage:

• High-volume teams (support, operations): Lower per-seat budgets, more seats
• Strategic teams (executives, analysts): Higher per-seat budgets, fewer seats
• Development teams: Higher session budgets for intensive work

Default Instructions

Provide role-specific instructions:

{
  "sales_team": {
    "defaultInstructions": "You are a sales assistant. Focus on customer insights, deal analysis, and revenue projections."
  },
  "support_team": {
    "defaultInstructions": "You are a customer support assistant. Be concise, empathetic, and solution-focused."
  },
  "analytics_team": {
    "defaultInstructions": "You are a data analyst. Provide detailed analysis with statistical rigor."
  }
}

Security Restrictions

Prevent access to sensitive data:

{
  "contractor_team": {
    "restrictedDatasets": ["employee_data", "financial_records"],
    "allowedToolkits": ["informer"],
    "allowWeb": false,
    "allowAttachments": false
  }
}

Team Management

Use team settings to delegate AI configuration to department managers without granting tenant-wide admin access.

Budget Monitoring

Team budget caps are soft limits checked at request time. Monitor usage frequently to prevent overages during high-activity periods.