# AI Policy

The AI Policy APIs enable you to create, manage, and enforce governance policies for AI operations across your organization. These policies help ensure compliance, security, and responsible AI usage at organization, workspace, or repository levels.

## Overview

AI Policies are flexible governance rules that can be applied at different organizational levels to control and monitor AI usage. They provide a powerful framework for:

* **Compliance Enforcement**: Ensure AI operations comply with regulatory requirements
* **Security Control**: Prevent sensitive data leakage through AI interactions
* **Content Moderation**: Define acceptable use policies for AI services
* **Risk Management**: Classify and respond to different risk levels
* **Audit Trail**: Track policy violations and enforcement actions

### Policy Scope Hierarchy

Policies can be created at three levels, forming an inheritance hierarchy:

1. **Organization-Level**: Applies to all workspaces and repositories in the organization
2. **Workspace-Level**: Applies to all repositories within a specific workspace
3. **Repository-Level**: Applies only to a specific repository

Lower-level policies can supplement (but not override) higher-level policies.

## Policy Components

### Risk Types

Classify policies based on their risk level:

* **LOW** - Informational policies, minimal impact if violated
* **MEDIUM** - Important policies with moderate business impact
* **HIGH** - Critical policies requiring immediate attention

### Action Types

Define what happens when a policy is violated:

| Action Type | Value | Behavior                                                    |
| ----------- | ----- | ----------------------------------------------------------- |
| Log Only    | 0     | Record the violation for audit purposes                     |
| Alert       | 1     | Log violation and send notifications to administrators      |
| Block       | 2     | Prevent the action from completing and alert administrators |

### Policy Content

Policy content is defined in natural language and describes:

* What actions are prohibited or required
* Context and rationale for the policy
* Specific examples of violations
* Any exceptions or special cases

**Example Policy Contents:**

```
"Do not allow sharing of personally identifiable information (PII) such as 
social security numbers, credit card numbers, or personal addresses in AI 
interactions."
```

```
"All API requests must include proper authentication. Do not allow anonymous 
or unauthenticated access to AI services."
```

```
"Prevent disclosure of proprietary source code, internal system architecture, 
or confidential business information through AI conversations."
```

## AI Policy API Calls

| Method                                                                 | API Reference                                                                                                                                 | Description                                                                   |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| <mark style="color:orange;">`POST`</mark>`/policy`                     | [**post\_\_policy**](/support-reference/platform-api-reference/ai-apis/ai-policy/post__policy.md)                                             | Create a new AI policy.                                                       |
| <mark style="color:blue;">`PUT`</mark>`/policy/{policyId}`             | [**put\_\_policy\_{policyId}**](/support-reference/platform-api-reference/ai-apis/ai-policy/put__policy_-policyid.md)                         | Update an existing policy.                                                    |
| <mark style="color:green;">`GET`</mark>`/policy`                       | [**get\_\_policy**](/support-reference/platform-api-reference/ai-apis/ai-policy/get__policy.md)                                               | List policies with optional filtering.                                        |
| <mark style="color:green;">`GET`</mark>`/policy/{policyId}`            | [**get\_\_policy\_{policyId}**](/support-reference/platform-api-reference/ai-apis/ai-policy/get__policy_-policyid.md)                         | Get detailed information about a specific policy.                             |
| <mark style="color:green;">`GET`</mark>`/policy/violations`            | [**get\_\_policy\_violations**](/support-reference/platform-api-reference/ai-apis/ai-policy/get__policy_violations.md)                        | Retrieve a list of policy violations that have occurred during AI operations. |
| <mark style="color:green;">`GET`</mark>`/policy/{policyId}/violations` | [**get\_\_policy\_{policyId}\_violations**](/support-reference/platform-api-reference/ai-apis/ai-policy/get__policy_-policyid-_violations.md) | Retrieve all violations for a specific policy.                                |
| <mark style="color:green;">`GET`</mark>`/policy/alerts`                | [**get\_\_policy\_alerts**](/support-reference/platform-api-reference/ai-apis/ai-policy/get__policy_alerts.md)                                | Retrieve all policy alerts across your organization with optional filtering.  |
| <mark style="color:green;">`GET`</mark>`/policy/{policyId}/alerts`     | [**get\_\_policy\_{policyId}\_alerts**](/support-reference/platform-api-reference/ai-apis/ai-policy/get__policy_-policyid-_alerts.md)         | Retrieve all alerts for a specific policy.                                    |
| <mark style="color:red;">`DELETE`</mark>`/policy/{policyId}`           | [**delete\_\_policy\_{policyId}**](/support-reference/platform-api-reference/ai-apis/ai-policy/delete__policy_-policyid.md)                   | Permanently delete an AI governance policy.                                   |

## Common Use Cases

### 1. Creating an Organization-Level Policy

```typescript
// Create a high-risk policy that blocks PII sharing across the entire organization
const response = await client.createPolicy({
  name: "PII Protection Policy",
  content: "Do not allow sharing of personally identifiable information (PII) such as social security numbers, credit card numbers, or personal addresses in AI interactions.",
  riskType: "HIGH",
  actionType: 2, // Block
  orgId: "org-123",
  workspaceId: null, // Null = org-level
  repoId: null
});

console.log(`Created policy: ${response.policy.id}`);
```

### 2. Creating a Workspace-Level Policy

```typescript
// Create a medium-risk policy for a specific workspace
const response = await client.createPolicy({
  name: "Development Data Policy",
  content: "Do not use production data in development AI interactions. Always use anonymized or synthetic data for testing.",
  riskType: "MEDIUM",
  actionType: 1, // Alert
  orgId: "org-123",
  workspaceId: "workspace-dev",
  repoId: null
});
```

### 3. Creating a Repository-Specific Policy

```typescript
// Create a repository-specific policy
const response = await client.createPolicy({
  name: "Customer Support Bot Policy",
  content: "Only provide information from approved documentation. Do not speculate or provide unverified information.",
  riskType: "MEDIUM",
  actionType: 1, // Alert
  orgId: "org-123",
  workspaceId: "workspace-support",
  repoId: "repo-support-bot"
});
```

### 4. Listing Policies

```typescript
// Get all organization policies
const orgPolicies = await client.getPolicies({
  orgId: "org-123"
});

// Get workspace-specific policies
const workspacePolicies = await client.getPolicies({
  orgId: "org-123",
  workspaceId: "workspace-456"
});

// Get repository-specific policies
const repoPolicies = await client.getPolicies({
  orgId: "org-123",
  workspaceId: "workspace-456",
  repoId: "repo-789"
});

// Display policies
orgPolicies.policies.forEach(policy => {
  console.log(`${policy.name} (${policy.riskType})`);
  console.log(`  Action: ${policy.actionType === 2 ? 'Block' : policy.actionType === 1 ? 'Alert' : 'Log'}`);
  console.log(`  Scope: ${policy.repoId ? 'Repository' : policy.workspaceId ? 'Workspace' : 'Organization'}`);
});
```

### 5. Updating a Policy

```typescript
// Update policy to increase severity
await client.updatePolicy("policy-123", {
  riskType: "HIGH",
  actionType: 2 // Change from alert to block
});

// Update policy content
await client.updatePolicy("policy-123", {
  content: "Enhanced policy description with additional examples and clarifications."
});
```

### 6. Deleting a Policy

```typescript
// Delete an obsolete policy
await client.deletePolicy("policy-123");
console.log("Policy deleted successfully");
```

## Policy Design Best Practices

### 1. Clear and Specific Content

**Good:**

```
"Do not share customer email addresses, phone numbers, or physical addresses 
in AI conversations. This includes partial information that could be used to 
identify individuals."
```

**Avoid:**

```
"Don't share personal info."
```

### 2. Appropriate Risk Classification

* **HIGH**: Data breaches, regulatory violations, security threats
* **MEDIUM**: Business process violations, quality issues
* **LOW**: Best practice recommendations, style guidelines

### 3. Balanced Action Types

* Use **Block (2)** sparingly for critical security policies
* Use **Alert (1)** for important policies that need review
* Use **Log (0)** for informational policies and monitoring

### 4. Layered Policy Strategy

```typescript
// Layer 1: Organization-level baseline
await client.createPolicy({
  name: "Baseline Security Policy",
  content: "Never share passwords, API keys, or authentication tokens.",
  riskType: "HIGH",
  actionType: 2,
  orgId: "org-123",
  workspaceId: null,
  repoId: null
});

// Layer 2: Workspace-specific policies
await client.createPolicy({
  name: "Healthcare Compliance",
  content: "Comply with HIPAA regulations. Never share patient health information.",
  riskType: "HIGH",
  actionType: 2,
  orgId: "org-123",
  workspaceId: "workspace-healthcare",
  repoId: null
});

// Layer 3: Repository-specific policies
await client.createPolicy({
  name: "Patient Portal Guidelines",
  content: "Only provide general health information. Direct specific medical questions to healthcare providers.",
  riskType: "MEDIUM",
  actionType: 1,
  orgId: "org-123",
  workspaceId: "workspace-healthcare",
  repoId: "repo-patient-portal"
});
```

## Permission Model

Policy operations require different permission levels based on scope:

### Organization-Level Policies

* **Create**: Organization owner or administrator
* **Read**: All organization members can read org-level policies
* **Update/Delete**: Organization owner or administrator

### Workspace-Level Policies

* **Create**: Organization administrators or workspace administrators
* **Read**: Workspace members can read workspace policies
* **Update/Delete**: Organization administrators or workspace administrators

### Repository-Level Policies

* **Create**: Users with repository access
* **Read**: Users with repository access
* **Update/Delete**: Users with repository write access

## Audit and Compliance

All policy operations maintain a complete audit trail:

### Creator Information

Each policy tracks:

* User who created it
* Creation timestamp
* Original policy configuration

### Update Tracking

Each update records:

* User who made the change
* Update timestamp
* Changed fields

### Example Audit Information

```typescript
const policy = await client.getPolicy("policy-123");

console.log("Created by:", policy.policy.createdBy.email);
console.log("Created at:", policy.policy.createdAt);
console.log("Last updated by:", policy.policy.lastUpdatedBy.email);
console.log("Last updated at:", policy.policy.lastUpdatedAt);
```

## Policy Enforcement

Policies are enforced in real-time during AI operations:

1. **Request Evaluation**: When an AI operation occurs, all applicable policies are evaluated
2. **Policy Matching**: Policies are matched based on hierarchy (org → workspace → repo)
3. **Action Execution**: Based on policy actionType:
   * **Log (0)**: Violation is recorded
   * **Alert (1)**: Violation is recorded and administrators are notified
   * **Block (2)**: Operation is prevented and administrators are notified

## Error Handling

Common error scenarios when working with policies:

### 400 Bad Request

**Causes:**

* Missing required fields
* Invalid repoId/workspaceId combination
* No fields provided for update

```typescript
try {
  await client.createPolicy(policyData);
} catch (error) {
  if (error.status === 400) {
    console.error("Validation error:", error.message);
  }
}
```

### 403 Forbidden

**Causes:**

* User doesn't belong to the organization
* Insufficient permissions for policy scope level
* Attempting to modify policy user doesn't have access to

```typescript
try {
  await client.updatePolicy("policy-123", updates);
} catch (error) {
  if (error.status === 403) {
    console.error("Permission denied:", error.message);
  }
}
```

### 404 Not Found

**Causes:**

* Policy doesn't exist
* Policy has been deleted

```typescript
try {
  await client.getPolicy("invalid-policy-id");
} catch (error) {
  if (error.status === 404) {
    console.error("Policy not found");
  }
}
```

## TypeScript Client Library

The Flashback TypeScript client provides convenient methods for all policy operations:

```typescript
import { FlashbackClient } from '@flashbacktech/flashbackclient';

const client = new FlashbackClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://backend.flashback.tech'
});

// Create policy
const created = await client.createPolicy({
  name: "My Policy",
  content: "Policy content...",
  riskType: "HIGH",
  actionType: 2,
  orgId: "org-123",
  workspaceId: null,
  repoId: null
});

// List policies
const policies = await client.getPolicies({
  orgId: "org-123",
  workspaceId: "workspace-456"
});

// Get single policy
const policy = await client.getPolicy("policy-id");

// Update policy
await client.updatePolicy("policy-id", {
  name: "Updated Name",
  riskType: "MEDIUM"
});

// Delete policy
await client.deletePolicy("policy-id");
```

## Integration Examples

### Setting Up a Comprehensive Policy Framework

```typescript
class PolicyManager {
  constructor(private client: FlashbackClient, private orgId: string) {}

  async setupBaselinePolicies() {
    // Security policies
    await this.createSecurityPolicies();
    
    // Compliance policies
    await this.createCompliancePolicies();
    
    // Quality policies
    await this.createQualityPolicies();
  }

  private async createSecurityPolicies() {
    // PII Protection
    await this.client.createPolicy({
      name: "PII Protection",
      content: "Never share personally identifiable information...",
      riskType: "HIGH",
      actionType: 2,
      orgId: this.orgId,
      workspaceId: null,
      repoId: null
    });

    // Credential Security
    await this.client.createPolicy({
      name: "Credential Security",
      content: "Never share passwords, API keys, tokens, or secrets...",
      riskType: "HIGH",
      actionType: 2,
      orgId: this.orgId,
      workspaceId: null,
      repoId: null
    });
  }

  private async createCompliancePolicies() {
    // Add compliance-specific policies
  }

  private async createQualityPolicies() {
    // Add quality-related policies
  }
}

// Usage
const manager = new PolicyManager(client, "org-123");
await manager.setupBaselinePolicies();
```

## Best Practices Summary

1. **Start with Organization-Level**: Create baseline security and compliance policies at org level
2. **Be Specific**: Write clear, specific policy content with examples
3. **Use Appropriate Actions**: Reserve blocking for critical policies
4. **Layer Policies**: Use hierarchy to create comprehensive coverage
5. **Review Regularly**: Audit and update policies as requirements change
6. **Test Policies**: Verify policies work as expected before wide deployment
7. **Document Intent**: Include rationale in policy content
8. **Monitor Violations**: Regularly review policy violations (see Violations APIs)

## Related Documentation

* [AI LLM Management APIs](https://github.com/flashbacknetwork/flashback-usermanual/blob/main/support-reference/platform-api-reference/ai-apis/llm-management/README.md) - Configure AI provider connections
* [AI API Keys](/support-reference/platform-api-reference/ai-apis/ai-api-keys.md) - Manage repository-specific API keys for AI operations
* [Policy Violations](https://github.com/flashbacknetwork/flashback-usermanual/blob/main/support-reference/platform-api-reference/ai-apis/policy-violations/README.md) - Monitor and analyze policy violations

## Next Steps

1. Design your policy framework based on organizational requirements
2. Create organization-level baseline policies
3. Add workspace-specific policies for different teams or projects
4. Create repository-specific policies for specialized use cases
5. Monitor policy violations and adjust as needed
6. Regularly review and update policies to maintain effectiveness


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flashback.tech/support-reference/platform-api-reference/ai-apis/ai-policy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.