AI Configuration API

The AI Configuration API provides comprehensive endpoints for customizing AI behavior, managing templates, configuring branding, and controlling AI-powered features across the ZServed platform.

Authentication

All AI Configuration API endpoints require admin authentication:

Authorization: Bearer <admin_jwt_token>

Base URL

https://your-domain.com/api/admin/ai-configuration

Endpoints Overview

Endpoint	Method	Description
`/templates`	GET, POST, PUT, DELETE	Manage AI prompt templates
`/branding`	GET, POST, PUT	Configure custom branding
`/style-guide`	GET, POST, PUT	Manage style guide settings
`/clauses`	GET, POST, PUT, DELETE	Legal clauses management
`/page-config`	GET, POST, PUT	Page generation configuration
`/generate-page`	POST	Generate custom pages

Templates API

List Templates

Get all AI prompt templates for the tenant.

GET /api/admin/ai-configuration/templates

Response:

{
  "success": true,
  "templates": [
    {
      "id": "motion-template-1",
      "name": "Motion for Summary Judgment",
      "category": "motions",
      "type": "legal-document",
      "prompt": "Generate a motion for summary judgment with the following details: {case_details}",
      "variables": ["case_details", "jurisdiction", "legal_standard"],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z",
      "active": true
    }
  ],
  "total": 15,
  "categories": ["motions", "pleadings", "contracts", "correspondence"]
}

Create Template

Create a new AI prompt template.

POST /api/admin/ai-configuration/templates
Content-Type: application/json

Request Body:

{
  "name": "Contract Review Template",
  "category": "contracts",
  "type": "analysis",
  "prompt": "Review the following contract and identify key terms, potential issues, and recommendations: {contract_text}",
  "variables": ["contract_text", "client_preferences", "risk_tolerance"],
  "metadata": {
    "jurisdiction": "michigan",
    "practice_area": "business-law",
    "complexity": "intermediate"
  },
  "active": true
}

Response:

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "Contract Review Template",
    "category": "contracts",
    "type": "analysis",
    "prompt": "Review the following contract...",
    "variables": ["contract_text", "client_preferences", "risk_tolerance"],
    "created_at": "2024-01-21T09:15:00Z",
    "active": true
  }
}

Update Template

Update an existing template.

PUT /api/admin/ai-configuration/templates/{template_id}
Content-Type: application/json

Request Body:

{
  "name": "Updated Contract Review Template",
  "prompt": "Thoroughly review the following contract, paying special attention to liability clauses: {contract_text}",
  "variables": ["contract_text", "liability_focus", "jurisdiction"],
  "active": true
}

Delete Template

Delete a template.

DELETE /api/admin/ai-configuration/templates/{template_id}

Response:

{
  "success": true,
  "message": "Template deleted successfully"
}

Branding API

Get Branding Configuration

Retrieve current branding settings.

GET /api/admin/ai-configuration/branding

Response:

{
  "success": true,
  "branding": {
    "firm_name": "Smith & Associates Law Firm",
    "logo_url": "/tenant-assets/smith-associates/logo.png",
    "primary_color": "#1e40af",
    "secondary_color": "#3b82f6",
    "accent_color": "#10b981",
    "font_family": "Inter",
    "tone": "professional",
    "language_style": "formal",
    "specialties": ["family-law", "estate-planning", "business-law"],
    "jurisdiction": "michigan",
    "bar_number": "P12345",
    "contact_info": {
      "address": "123 Main St, Grand Rapids, MI 49503",
      "phone": "(616) 555-0123",
      "email": "info@smithlaw.com",
      "website": "https://smithlaw.com"
    }
  }
}

Update Branding

Update branding configuration.

POST /api/admin/ai-configuration/branding
Content-Type: application/json

Request Body:

{
  "firm_name": "Smith & Associates Law Firm",
  "primary_color": "#1e40af",
  "secondary_color": "#3b82f6",
  "accent_color": "#10b981",
  "tone": "professional",
  "language_style": "formal",
  "specialties": ["family-law", "estate-planning"],
  "jurisdiction": "michigan",
  "contact_info": {
    "address": "123 Main St, Grand Rapids, MI 49503",
    "phone": "(616) 555-0123",
    "email": "info@smithlaw.com"
  }
}

Response:

{
  "success": true,
  "message": "Branding updated successfully",
  "branding": {
    "firm_name": "Smith & Associates Law Firm",
    "primary_color": "#1e40af",
    "updated_at": "2024-01-21T11:30:00Z"
  }
}

Style Guide API

Get Style Guide

Retrieve writing and communication style preferences.

GET /api/admin/ai-configuration/style-guide

Response:

{
  "success": true,
  "style_guide": {
    "writing_style": "formal",
    "tone": "professional",
    "voice": "authoritative",
    "person": "third",
    "tense": "present",
    "language_preferences": {
      "avoid_jargon": true,
      "explain_legal_terms": true,
      "use_plain_language": false,
      "include_citations": true
    },
    "document_formatting": {
      "header_style": "traditional",
      "citation_format": "bluebook",
      "paragraph_style": "block",
      "numbering_system": "outline"
    },
    "communication_preferences": {
      "client_communication": "accessible",
      "court_filings": "formal",
      "internal_memos": "professional"
    }
  }
}

Update Style Guide

Update style guide preferences.

POST /api/admin/ai-configuration/style-guide
Content-Type: application/json

Request Body:

{
  "writing_style": "formal",
  "tone": "professional",
  "voice": "authoritative",
  "language_preferences": {
    "avoid_jargon": true,
    "explain_legal_terms": true,
    "use_plain_language": false
  },
  "document_formatting": {
    "citation_format": "bluebook",
    "paragraph_style": "block"
  }
}

Legal Clauses API

List Clauses

Get available legal clauses and templates.

GET /api/admin/ai-configuration/clauses

Query Parameters:

category - Filter by clause category
type - Filter by clause type
active - Filter by active status

Response:

{
  "success": true,
  "clauses": [
    {
      "id": "clause_001",
      "name": "Standard Liability Limitation",
      "category": "liability",
      "type": "limitation",
      "content": "IN NO EVENT SHALL [PARTY] BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES...",
      "variables": ["party_name", "liability_cap", "exceptions"],
      "jurisdiction": "michigan",
      "practice_area": "contracts",
      "active": true,
      "created_at": "2024-01-10T08:00:00Z"
    }
  ],
  "total": 25,
  "categories": ["liability", "indemnification", "termination", "confidentiality"]
}

Create Clause

Add a new legal clause template.

POST /api/admin/ai-configuration/clauses
Content-Type: application/json

Request Body:

{
  "name": "Michigan Non-Compete Clause",
  "category": "employment",
  "type": "non-compete",
  "content": "Employee agrees not to engage in any business that competes with Company within [GEOGRAPHIC_SCOPE] for a period of [TIME_PERIOD] following termination of employment.",
  "variables": ["geographic_scope", "time_period", "business_definition"],
  "jurisdiction": "michigan",
  "practice_area": "employment-law",
  "notes": "Ensure compliance with Michigan non-compete restrictions",
  "active": true
}

Update Clause

Update an existing legal clause.

PUT /api/admin/ai-configuration/clauses/{clause_id}
Content-Type: application/json

Request Body:

{
  "content": "Updated clause content with new legal requirements...",
  "variables": ["updated_variable_list"],
  "notes": "Updated for 2024 Michigan law changes",
  "active": true
}

Page Configuration API

Get Page Config

Retrieve page generation configuration.

GET /api/admin/ai-configuration/page-config

Response:

{
  "success": true,
  "config": {
    "homepage": {
      "hero_style": "professional",
      "practice_areas_display": "grid",
      "testimonials_enabled": true,
      "contact_form_style": "inline"
    },
    "practice_areas": {
      "detail_level": "comprehensive",
      "include_faqs": true,
      "include_case_studies": false,
      "call_to_action": "consultation"
    },
    "about": {
      "attorney_profiles": "detailed",
      "firm_history": true,
      "achievements": true,
      "community_involvement": true
    },
    "contact": {
      "form_fields": ["name", "email", "phone", "case_type", "message"],
      "office_hours": true,
      "map_integration": true,
      "emergency_contact": false
    }
  }
}

Update Page Config

Update page generation settings.

POST /api/admin/ai-configuration/page-config
Content-Type: application/json

Request Body:

{
  "homepage": {
    "hero_style": "modern",
    "practice_areas_display": "carousel",
    "testimonials_enabled": true
  },
  "practice_areas": {
    "detail_level": "comprehensive",
    "include_faqs": true,
    "call_to_action": "consultation"
  }
}

Page Generation API

Generate Custom Page

Generate a custom page using AI.

POST /api/admin/ai-configuration/generate-page
Content-Type: application/json

Request Body:

{
  "page_type": "practice_area",
  "page_name": "Family Law",
  "parameters": {
    "focus_areas": ["divorce", "child custody", "adoption"],
    "target_audience": "families in crisis",
    "tone": "compassionate but professional",
    "include_faqs": true,
    "include_case_studies": false,
    "call_to_action": "free consultation"
  },
  "branding": {
    "firm_name": "Smith & Associates",
    "location": "Grand Rapids, Michigan",
    "specialties": ["family law", "mediation"]
  }
}

Response:

{
  "success": true,
  "page": {
    "id": "page_family_law_001",
    "title": "Family Law Services - Smith & Associates",
    "url_slug": "family-law",
    "content": {
      "hero": {
        "headline": "Compassionate Family Law Representation in Grand Rapids",
        "subtitle": "Protecting your family's future with experienced legal guidance",
        "cta_text": "Schedule Your Free Consultation"
      },
      "sections": [
        {
          "type": "services",
          "title": "Our Family Law Services",
          "content": "..."
        },
        {
          "type": "process",
          "title": "How We Can Help",
          "content": "..."
        }
      ],
      "faqs": [
        {
          "question": "How long does a divorce take in Michigan?",
          "answer": "..."
        }
      ]
    },
    "metadata": {
      "seo_title": "Family Law Attorney Grand Rapids | Smith & Associates",
      "meta_description": "Experienced family law attorneys in Grand Rapids, MI. Divorce, custody, adoption services. Free consultation.",
      "keywords": ["family law", "divorce attorney", "Grand Rapids", "Michigan"]
    },
    "generated_at": "2024-01-21T15:45:00Z"
  }
}

AI Model Configuration

Get Model Settings

Retrieve current AI model configuration.

GET /api/admin/ai-configuration/models

Response:

{
  "success": true,
  "models": {
    "primary": {
      "model": "gpt-4-turbo-preview",
      "temperature": 0.1,
      "max_tokens": 4000,
      "top_p": 0.95,
      "frequency_penalty": 0.0,
      "presence_penalty": 0.0
    },
    "analysis": {
      "model": "gpt-4",
      "temperature": 0.05,
      "max_tokens": 2000
    },
    "embeddings": {
      "model": "text-embedding-3-large",
      "dimensions": 1536
    }
  },
  "usage_limits": {
    "daily_tokens": 100000,
    "monthly_tokens": 2000000,
    "concurrent_requests": 10
  }
}

Update Model Settings

Update AI model configuration.

PUT /api/admin/ai-configuration/models
Content-Type: application/json

Request Body:

{
  "primary": {
    "temperature": 0.2,
    "max_tokens": 3500,
    "top_p": 0.9
  },
  "usage_limits": {
    "daily_tokens": 150000,
    "concurrent_requests": 15
  }
}

Error Handling

All endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "code": "INVALID_TEMPLATE",
    "message": "Template validation failed",
    "details": {
      "field": "prompt",
      "issue": "Missing required variables"
    }
  }
}

Common Error Codes

UNAUTHORIZED - Invalid or missing authentication
FORBIDDEN - Insufficient permissions
INVALID_REQUEST - Malformed request body
INVALID_TEMPLATE - Template validation failed
RESOURCE_NOT_FOUND - Template/config not found
RATE_LIMIT_EXCEEDED - Too many requests
AI_SERVICE_ERROR - OpenAI API error
VALIDATION_ERROR - Input validation failed

Rate Limiting

API endpoints are rate limited:

General endpoints: 100 requests per minute
AI generation endpoints: 20 requests per minute
Template operations: 50 requests per minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642780800

Webhooks

Configure webhooks for AI configuration events:

POST /api/admin/ai-configuration/webhooks
Content-Type: application/json

Request Body:

{
  "url": "https://your-app.com/webhooks/ai-config",
  "events": ["template.created", "template.updated", "branding.updated"],
  "secret": "webhook_secret_key"
}

Webhook Events

template.created - New template created
template.updated - Template modified
template.deleted - Template removed
branding.updated - Branding configuration changed
style_guide.updated - Style guide modified
page.generated - New page generated

SDK Examples

JavaScript/TypeScript

import { ZServedAPI } from '@zserved/api-client';

const api = new ZServedAPI({
  baseURL: 'https://your-domain.com/api',
  adminToken: 'your_admin_jwt_token'
});

// Create a new template
const template = await api.aiConfig.templates.create({
  name: 'Motion for Summary Judgment',
  category: 'motions',
  prompt: 'Generate a motion for summary judgment...',
  variables: ['case_details', 'jurisdiction']
});

// Update branding
await api.aiConfig.branding.update({
  firm_name: 'Updated Firm Name',
  primary_color: '#1e40af'
});

// Generate a page
const page = await api.aiConfig.generatePage({
  page_type: 'practice_area',
  page_name: 'Personal Injury',
  parameters: {
    focus_areas: ['auto accidents', 'slip and fall'],
    tone: 'empathetic'
  }
});

Python

from zserved_api import ZServedAPI

api = ZServedAPI(
    base_url='https://your-domain.com/api',
    admin_token='your_admin_jwt_token'
)

# Create template
template = api.ai_config.templates.create({
    'name': 'Contract Review Template',
    'category': 'contracts',
    'prompt': 'Review the following contract...',
    'variables': ['contract_text']
})

# Update style guide
api.ai_config.style_guide.update({
    'writing_style': 'formal',
    'tone': 'professional'
})

For more examples and advanced usage, see the AI Configuration Guide.