Skip to content

REST API Overview

The HG Content Generation System provides multiple REST API interfaces for different use cases and integration scenarios. This document provides an overview of all available APIs and their intended purposes.

API Endpoints Overview

Content Production Module (CPM) API

Base URL: https://cpm.hgcontent.com
Purpose: Internal content generation service with advanced features
Authentication: Bearer token (JWT) or API key

The CPM API is the core content generation service used by the frontend dashboard and internal services. It provides:

  • Multi-provider LLM support (OpenAI, Anthropic, Google, Groq, Ollama)
  • Advanced job queuing and processing
  • Real-time status updates via WebSocket
  • Comprehensive job management and history

Key endpoints: - POST /api/generate - Create content generation jobs - GET /api/jobs/{jobId} - Get job status and results - GET /api/jobs - List jobs with filtering - GET /api/providers/status - Check LLM provider availability

External API (Public)

Base URL: https://api.hgcontent.com/api/v1
Purpose: Public-facing API for third-party integrations
Authentication: API key (X-API-Key header)

The External API provides a simplified, stable interface for external clients and integrations:

  • Standardized content type support (SEO articles, hyperlocal, GBP posts)
  • Async job processing with polling-based status checks
  • Simple authentication model
  • OpenAPI 3.0 specification compliance

Key endpoints: - POST /content/generate - Create content generation request - GET /jobs/{jobId}/status - Get job status - GET /jobs/{jobId}/content - Retrieve generated content

Instructions Module (IM) API

Base URL: https://im.hgcontent.com
Purpose: Prompt generation and instruction management
Authentication: Internal service authentication

The IM API handles prompt engineering and instruction generation:

  • Dynamic prompt template management
  • Context-aware instruction generation
  • Template versioning and A/B testing
  • Performance analytics for prompts

Key endpoints: - POST /api/instructions/generate - Generate instructions for content requests - GET /api/templates - List available prompt templates - PUT /api/templates/{id} - Update prompt templates

API Feature Comparison

Feature CPM API External API IM API
Authentication JWT/API Key API Key Internal
Real-time Updates WebSocket Polling N/A
Content Types All types 3 standard types Template-based
LLM Provider Choice Full control Automatic N/A
Job Management Full CRUD Read-only N/A
Rate Limiting Per-user quotas Per-key limits Internal only
Documentation Internal docs OpenAPI spec Internal docs

Authentication Methods

API Key Authentication

GET /api/endpoint
X-API-Key: your-api-key-here
Content-Type: application/json

Bearer Token Authentication

GET /api/endpoint
Authorization: Bearer your-jwt-token-here
Content-Type: application/json

Response Formats

All APIs return JSON responses with consistent error handling:

Success Response

{
  "success": true,
  "data": {
    "jobId": "job-123",
    "status": "processing"
  }
}

Error Response

{
  "success": false,
  "error": "Invalid request",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "keywords",
    "message": "Keywords are required"
  }
}

Rate Limiting

External API

  • Rate Limit: 100 requests per hour per API key
  • Burst Limit: 10 requests per minute
  • Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

CPM API

  • Rate Limit: Based on user subscription plan
  • Concurrent Jobs: Limited per client
  • Monthly Quotas: Content generation limits apply

Health and Monitoring

All APIs provide health check endpoints:

  • GET /healthz - Basic health check
  • GET /readyz - Readiness check with dependency validation
  • GET /metrics - Prometheus metrics (internal)

OpenAPI Specifications

External API Specification

The External API follows OpenAPI 3.1 specifications:

CPM API Specification

Auto-generated from FastAPI application:

CPM OpenAPI

The CPM API specification is automatically generated and available at: - JSON: https://cpm.hgcontent.com/openapi.json - Interactive Docs: https://cpm.hgcontent.com/docs - ReDoc: https://cpm.hgcontent.com/redoc

SDK Support

Official SDKs

Community SDKs

Community-contributed SDKs are available for: - PHP - Ruby
- Go - .NET

See the Developer Resources section for links and documentation.

Migration Guides

From v0.x to v1.0

  • Updated authentication model
  • New job status workflow
  • Enhanced error responses
  • Breaking changes in content type schemas

See the Migration Guide for detailed upgrade instructions.

Support and Resources

  • API Documentation: Complete endpoint references
  • Developer Guide: Setup and integration examples
  • Postman Collection: Pre-configured API requests
  • GitHub Repository: Source code and issue tracking
  • Community Forum: Developer discussions and support

Getting Started

  1. Choose Your API: Select the appropriate API for your use case
  2. Get API Keys: Register and obtain authentication credentials
  3. Review Documentation: Read endpoint-specific documentation
  4. Test Integration: Use sandbox environment for development
  5. Go Live: Deploy with production credentials

For detailed integration examples, see the Quick Start Guide.