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://hg-content-production.up.railway.app (production domain: https://cpm.hgcontent.com)
Purpose: Internal content generation service with advanced features
Authentication: Bearer token (hashed API keys stored in api_keys)

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

  • OpenRouter LLM aggregation (OpenAI, Anthropic, Groq, Gemini models via a single provider)
  • Advanced job queuing and processing
  • Real-time status updates via WebSocket
  • Comprehensive job management and history

Key endpoints: - POST /generate - Create content generation jobs (requires OpenRouter user key) - GET /jobs/{jobId} - Get job status and results - GET /jobs - List jobs with filtering - GET /providers/status - Check LLM provider catalogue, pricing, and key requirements

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

CPM API (Bearer API Key)

All CPM requests use bcrypt-hashed API keys stored in the api_keys table. Send the plaintext key in the Authorization header:

Authorization: Bearer cpm_live_yourplaintextkey
Content-Type: application/json

Provisioning keys via Supabase SQL:

INSERT INTO api_keys (client_id, name, key_hash, is_active)
VALUES (
  '550e8400-e29b-41d4-a716-446655440000',
  'Production Integration',
  crypt('cpm_live_replace_me', gen_salt('bf')),
  true
);

Rotate keys regularly and store plaintext values in a secure secrets manager.

External API (X-API-Key)

External API consumers continue to send the X-API-Key header:

X-API-Key: your-external-api-key
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.