This document describes the Admin API endpoints for managing AI features, configurations, and analytics in TendSocial.

Base URL: /api/adminAuthentication: Requires isSuperAdmin: true in User JWT.

Table of Contents

• Global Settings
• AI Configuration
• AI Gateway
• A/B Testing
• AI Analytics
• Company AI Configuration

---

Global Settings

Manage system-wide settings.

Get Global Settings

GET /settings

Response: 200 OK

{
  "id": "default",
  "defaultTrialDays": 14
}

Update Global Settings

PUT /settings

Request Body:

{
  "defaultTrialDays": 30
}

Response: 200 OK

---

AI Configuration

Manage global default configurations for AI tasks.

List Global Configurations

GET /ai-config

Returns all global AI model configurations.

Response: 200 OK

[
  {
    "task": "social_post_generation",
    "provider": "openai",
    "model": "gpt-4",
    "maxTokens": 2000,
    "temperature": 0.7,
    "inputCostPer1M": 3000,
    "outputCostPer1M": 6000
  }
]

Update Global Configuration

PUT /ai-config/:task

Update the default configuration for a specific task.

Parameters:

• task: The task identifier (e.g., social_post_generation)

Request Body:

{
  "provider": "anthropic",
  "model": "claude-3-opus-20240229",
  "maxTokens": 4000,
  "temperature": 0.5,
  "inputCostPer1M": 1500,
  "outputCostPer1M": 7500
}

Response: 200 OK

---

AI Gateway

Manage the active AI provider adapter and cache.

Get Gateway Status

GET /gateway/status

Response: 200 OK

{
  "activeAdapter": "vercel",
  "availableAdapters": ["vercel", "direct"],
  "status": "online"
}

Switch Adapter

POST /gateway/switch

Switch the active AI adapter (e.g., from Vercel AI SDK to Direct API calls).

Request Body:

{
  "adapter": "direct"
}

Response: 200 OK

Clear Gateway Cache

POST /gateway/clear-cache

Clears the in-memory LRU cache for AI responses.

Response: 200 OK

---

A/B Testing

Manage A/B tests for AI prompts and models.

List A/B Tests

GET /ab-tests

Response: 200 OK

Create A/B Test

POST /ab-tests

Request Body:

{
  "name": "GPT-4 vs Claude 3 for Blog Posts",
  "task": "blog_post_generation",
  "description": "Testing which model produces better engagement",
  "isActive": true,
  "variants": [
    {
      "name": "gpt-4-turbo",
      "provider": "openai",
      "model": "gpt-4-turbo",
      "weight": 50,
      "temperature": 0.7,
      "maxTokens": 4000,
      "inputCostPer1M": 1000,
      "outputCostPer1M": 3000
    },
    {
      "name": "claude-3-sonnet",
      "provider": "anthropic",
      "model": "claude-3-sonnet-20240229",
      "weight": 50,
      "temperature": 0.7,
      "maxTokens": 4000,
      "inputCostPer1M": 300,
      "outputCostPer1M": 1500
    }
  ],
  "targetCompanyIds": [], // Optional: restrict to specific companies
  "targetUserIds": []     // Optional: restrict to specific users
}

Response: 201 Created

Update A/B Test

PUT /ab-tests/:id

Request Body: (Partial of Create Body)

Delete A/B Test

DELETE /ab-tests/:id

Get A/B Test Results

GET /ab-tests/:id/results

Returns aggregated usage statistics for each variant.

Response: 200 OK

{
  "test": { ... },
  "results": [
    {
      "variant": "gpt-4-turbo",
      "count": 150,
      "avgLatency": 2500,
      "avgCost": 4.5,
      "totalCost": 675
    },
    {
      "variant": "claude-3-sonnet",
      "count": 145,
      "avgLatency": 1800,
      "avgCost": 1.2,
      "totalCost": 174
    }
  ]
}

---

AI Analytics

View global and company-level AI usage statistics.

Global Summary

GET /ai-analytics/summary

Query Parameters:

• startDate (ISO Date)
• endDate (ISO Date)

Response: 200 OK

{
  "textGeneration": {
    "calls": 1250,
    "costCents": 5430,
    "tokens": 1500000
  },
  "imageGeneration": {
    "calls": 50,
    "costCents": 200
  },
  "totalCostCents": 5630
}

Analytics by Dimension

GET /ai-analytics/by-dimension

Group usage by model, provider, or task.

Query Parameters:

• dimension: model | provider | task
• startDate, endDate

Response: 200 OK

[
  {
    "key": "gpt-4",
    "count": 800,
    "costCents": 4000,
    "tokens": 1000000,
    "avgLatency": 2100
  },
  {
    "key": "claude-3-opus",
    "count": 450,
    "costCents": 1430,
    "tokens": 500000,
    "avgLatency": 3500
  }
]

Company Usage

GET /ai-analytics/company/:companyId

Response: 200 OK

{
  "stats": {
    "calls": 100,
    "costCents": 500,
    "tokens": 20000
  },
  "recentLogs": [ ... ]
}

---

Company AI Configuration

Manage company-specific overrides for AI settings.

Get Company Configs

GET /companies/:id/ai-config

Response: 200 OK

Update Company Config

PUT /companies/:id/ai-config/:task

Override the default configuration for a specific company and task.

Request Body:

{
  "provider": "openai",
  "model": "gpt-3.5-turbo", // Downgrade for cost saving example
  "useOwnKey": true,
  "apiKey": "sk-..." // Will be encrypted
}

Response: 200 OK

Reset Company Config

DELETE /companies/:id/ai-config/:task

Removes the override and reverts to global default.

Response: 200 OK