Skip to content

Internal API Reference

This document covers the internal service APIs used within the HG Content Generation System. These APIs are designed for inter-service communication and are not exposed publicly.

Overview

The internal API ecosystem consists of three main services:

  1. Content Production Module (CPM) - Core content generation service
  2. Instructions Module (IM) - Prompt and instruction management
  3. Strategy Management Module (SMM) - Client configuration and strategy management

Content Production Module (CPM) API

Base URL: http://cpm:8000 (internal) / https://cpm.hgcontent.com (external)
Authentication: Bearer token (JWT) or service-to-service API key

Core Endpoints

Content Generation

POST /api/generate
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "content_type": "seo_article",
  "client_id": "client-123",
  "instructions": "Generate an article about local SEO",
  "metadata": {
    "keywords": ["local seo", "small business"],
    "target_length": 1500,
    "tone": "professional"
  },
  "llm_config": {
    "provider": "openai",
    "model": "gpt-4",
    "temperature": 0.7
  }
}

Response: 

{
  "job_id": "job-uuid-123",
  "status": "queued",
  "estimated_completion_time": 45,
  "created_at": "2024-03-01T10:00:00Z"
}

Job Management

GET /api/jobs/{job_id}
Authorization: Bearer {jwt_token}

GET /api/jobs?client_id={client_id}&status={status}&limit=20&offset=0
Authorization: Bearer {jwt_token}

DELETE /api/jobs/{job_id}
Authorization: Bearer {jwt_token}

Provider Status

GET /api/providers/status
Authorization: Bearer {jwt_token}

Response: 

{
  "providers": {
    "openai": {
      "status": "healthy",
      "models": ["gpt-4", "gpt-3.5-turbo"],
      "rate_limit": {
        "requests_per_minute": 500,
        "tokens_per_minute": 90000
      }
    },
    "anthropic": {
      "status": "healthy",
      "models": ["claude-3-sonnet", "claude-3-haiku"]
    },
    "ollama": {
      "status": "degraded",
      "models": ["llama2", "mistral"],
      "message": "High response times detected"
    }
  }
}

WebSocket Endpoints

Real-time Job Updates

const ws = new WebSocket('wss://cpm.hgcontent.com/ws/jobs/{job_id}?token={jwt_token}');

ws.onmessage = function(event) {
  const update = JSON.parse(event.data);
  // {
  //   "job_id": "job-123",
  //   "status": "processing",
  //   "progress": 45,
  //   "current_step": "writing",
  //   "timestamp": "2024-03-01T10:15:30Z"
  // }
};

System Status Updates

const ws = new WebSocket('wss://cpm.hgcontent.com/ws/system?token={jwt_token}');

ws.onmessage = function(event) {
  const status = JSON.parse(event.data);
  // {
  //   "type": "provider_status_change",
  //   "provider": "openai",
  //   "status": "degraded",
  //   "message": "Rate limits increased"
  // }
};

FastAPI Auto-Generated Docs

The CPM service provides auto-generated OpenAPI documentation:

  • Swagger UI: https://cpm.hgcontent.com/docs
  • ReDoc: https://cpm.hgcontent.com/redoc
  • OpenAPI JSON: https://cpm.hgcontent.com/openapi.json

Example of accessing the auto-generated spec:

import requests

# Get the full OpenAPI specification
spec = requests.get("https://cpm.hgcontent.com/openapi.json").json()

# The spec includes all endpoints, models, and authentication schemes
print(spec["info"]["title"])  # "Content Production Module (CPM)"
print(len(spec["paths"]))     # Number of endpoints

Instructions Module (IM) API

Base URL: http://im:8001 (internal) / https://im.hgcontent.com (external)
Authentication: Service-to-service authentication via shared secret

Core Endpoints

Generate Instructions

POST /api/instructions/generate
X-Service-Token: {shared_secret}
Content-Type: application/json

{
  "content_type": "seo_article",
  "client_id": "client-123",
  "context": {
    "business_type": "local restaurant",
    "target_audience": "food enthusiasts",
    "keywords": ["italian cuisine", "downtown dining"],
    "tone": "warm and inviting"
  },
  "template_version": "v2.1"
}

Response: 

{
  "instruction_id": "inst-uuid-456",
  "instructions": "Write a comprehensive article about Italian cuisine...",
  "template_used": "seo_article_restaurant_v2.1",
  "estimated_tokens": 1200,
  "metadata": {
    "keywords_processed": 2,
    "tone_adjustments": ["warmth", "local_focus"],
    "seo_optimizations": ["local_keywords", "schema_markup"]
  }
}

Template Management

GET /api/templates
X-Service-Token: {shared_secret}

GET /api/templates/{template_id}
X-Service-Token: {shared_secret}

PUT /api/templates/{template_id}
X-Service-Token: {shared_secret}
Content-Type: application/json

{
  "name": "seo_article_restaurant_v2.2",
  "template": "Write a {tone} article about {business_type}...",
  "variables": ["tone", "business_type", "keywords"],
  "metadata": {
    "version": "2.2",
    "last_updated": "2024-03-01",
    "performance_metrics": {
      "avg_quality_score": 8.7,
      "usage_count": 1540
    }
  }
}

Analytics and Performance

GET /api/analytics/templates?start_date=2024-02-01&end_date=2024-03-01
X-Service-Token: {shared_secret}

GET /api/analytics/instructions/{instruction_id}/performance
X-Service-Token: {shared_secret}

Strategy Management Module (SMM) API

Base URL: http://smm:8002 (internal) / https://smm.hgcontent.com (external)
Authentication: JWT tokens for user context

Core Endpoints

Client Strategy Retrieval

GET /api/clients/{client_id}/strategy
Authorization: Bearer {jwt_token}

Response: 

{
  "client_id": "client-123",
  "strategy": {
    "content_guidelines": {
      "tone": "professional yet approachable",
      "target_audience": "small business owners",
      "key_messages": ["expertise", "local focus", "results-driven"]
    },
    "seo_rules": {
      "keyword_density": 0.02,
      "meta_description_length": 160,
      "required_elements": ["local_keywords", "business_name", "location"]
    },
    "templates": {
      "seo_article": "template-uuid-789",
      "hyperlocal": "template-uuid-790",
      "gbp_post": "template-uuid-791"
    }
  },
  "last_updated": "2024-02-28T14:30:00Z"
}

Client Hierarchy

GET /api/clients/{client_id}/hierarchy
Authorization: Bearer {jwt_token}

POST /api/clients/{parent_id}/children
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "name": "Local Branch Office",
  "inherit_strategy": true,
  "overrides": {
    "location": "San Francisco, CA",
    "local_keywords": ["SF restaurants", "Bay Area dining"]
  }
}

Template Assignment

PUT /api/clients/{client_id}/templates/{content_type}
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "template_id": "template-uuid-789",
  "customizations": {
    "tone_adjustment": 0.1,
    "keyword_emphasis": "high"
  }
}

Service-to-Service Communication

Authentication Flow

sequenceDiagram
    participant Frontend
    participant CPM
    participant IM
    participant SMM

    Frontend->>CPM: POST /api/generate (JWT)
    CPM->>CPM: Validate JWT
    CPM->>SMM: GET /api/clients/{id}/strategy (Service Token)
    SMM-->>CPM: Strategy Configuration
    CPM->>IM: POST /api/instructions/generate (Service Token)
    IM-->>CPM: Generated Instructions
    CPM->>CPM: Process Content Generation
    CPM-->>Frontend: Job Created Response

Service Discovery

Services use environment variables for service discovery:

# CPM Configuration
IM_SERVICE_URL=http://im:8001
SMM_SERVICE_URL=http://smm:8002
IM_SERVICE_TOKEN=shared-secret-123
SMM_SERVICE_TOKEN=shared-secret-456

# IM Configuration  
CPM_SERVICE_URL=http://cpm:8000
TEMPLATE_CACHE_TTL=3600

# SMM Configuration
CPM_SERVICE_URL=http://cpm:8000
STRATEGY_CACHE_TTL=1800

Health Checks and Circuit Breakers

Each service implements health checks and circuit breaker patterns:

# Health Check Response
{
  "status": "healthy",
  "timestamp": "2024-03-01T10:00:00Z",
  "version": "1.0.0",
  "dependencies": {
    "database": "healthy",
    "redis": "healthy",
    "external_apis": {
      "openai": "healthy",
      "anthropic": "degraded"
    }
  },
  "metrics": {
    "uptime_seconds": 86400,
    "requests_per_minute": 125,
    "error_rate": 0.02
  }
}

Error Propagation

Internal errors are propagated with context:

{
  "error": "Instruction generation failed",
  "service": "instructions_module",
  "trace_id": "trace-uuid-123",
  "timestamp": "2024-03-01T10:05:00Z",
  "details": {
    "template_id": "template-789",
    "client_id": "client-123",
    "error_code": "TEMPLATE_NOT_FOUND"
  },
  "upstream_errors": [
    {
      "service": "strategy_management",
      "error": "Client strategy not found",
      "code": "CLIENT_NOT_FOUND"
    }
  ]
}

Development and Testing

Local Development URLs

When running locally with Docker Compose:

  • CPM: http://localhost:8000
  • IM: http://localhost:8001
  • SMM: http://localhost:8002

Testing Endpoints

Each service provides testing endpoints:

# CPM Testing
POST /api/test/generate-mock
GET /api/test/providers/mock

# IM Testing  
POST /api/test/instructions/mock
GET /api/test/templates/validate/{template_id}

# SMM Testing
POST /api/test/strategy/validate
GET /api/test/clients/mock/{client_id}

API Versioning

All internal APIs use semantic versioning:

  • Headers: API-Version: 1.0 (current)
  • URL Versioning: /api/v1/ (future)
  • Backwards Compatibility: Maintained for at least 6 months

Rate Limiting

Internal services have different rate limiting strategies:

  • CPM: Per-client job limits
  • IM: Per-template generation limits
  • SMM: Per-client strategy update limits

Monitoring and Metrics

All services expose Prometheus metrics:

GET /metrics

Key metrics include: - Request duration histograms - Error rate counters - Active job gauges - Resource utilization

OpenAPI Specifications

Each service maintains OpenAPI specifications:

# Download service specs
curl http://cpm:8000/openapi.json > cpm-openapi.json
curl http://im:8001/openapi.json > im-openapi.json  
curl http://smm:8002/openapi.json > smm-openapi.json

Security Considerations

Service-to-Service Authentication

  • Shared secrets rotated monthly
  • JWT tokens with service-specific claims
  • mTLS for production environments

Network Security

  • Services communicate over internal network only
  • External access via API gateway/load balancer
  • Rate limiting at multiple layers

Data Security

  • PII encryption at rest and in transit
  • Audit logging for all operations
  • Role-based access control (RBAC)

For more details on security implementation, see the Deployment Guide.