External API Reference¶

The HG Content External API v1 provides a public-facing REST interface for third-party integrations and external clients. This API is designed for simplicity, stability, and ease of integration.

Base Information¶

• Base URL: https://api.hgcontent.com/api/v1
• API Version: v1.0.0
• Authentication: API Key (X-API-Key header)
• Content Type: application/json
• Response Format: JSON

Quick Start¶

1. Authentication¶

All requests require an API key in the X-API-Key header:

curl -X POST https://api.hgcontent.com/api/v1/content/generate \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"type": "seo_article", "businessId": "biz-123", "keywords": ["local seo", "marketing"]}'

2. Generate Content¶

Create a content generation request:

# SEO Article Example
curl -X POST https://api.hgcontent.com/api/v1/content/generate \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "seo_article",
    "businessId": "biz-123",
    "keywords": ["local seo", "digital marketing"],
    "targetLength": 1500,
    "tone": "professional"
  }'

Response:

{
  "jobId": "job-abc123",
  "status": "queued",
  "estimatedCompletionTime": 45
}

3. Check Job Status¶

Monitor job progress:

curl -H "X-API-Key: your-api-key" \
  https://api.hgcontent.com/api/v1/jobs/job-abc123/status

Response:

{
  "jobId": "job-abc123",
  "status": "processing",
  "progress": 65,
  "stepsCompleted": ["research", "outline", "writing"],
  "currentStep": "editing"
}

4. Retrieve Generated Content¶

Once status is "completed":

curl -H "X-API-Key: your-api-key" \
  https://api.hgcontent.com/api/v1/jobs/job-abc123/content

Response:

{
  "title": "The Ultimate Guide to Local SEO for Small Businesses",
  "body": "In today's competitive digital landscape...",
  "metaDescription": "Discover proven local SEO strategies...",
  "wordCount": 1487,
  "readingTime": 6,
  "seoScore": 94
}

Content Types¶

SEO Articles (seo_article)¶

Generate comprehensive SEO-optimized articles.

Required Fields: - type: "seo_article" - businessId: Your business identifier - keywords: Array of target keywords (min 1)

Optional Fields: - targetLength: Word count target (default: 1200) - tone: Content tone (professional, casual, friendly, etc.) - additionalInstructions: Custom requirements

Example:

{
  "type": "seo_article",
  "businessId": "local-bakery-ny",
  "keywords": ["artisan bread", "sourdough", "NYC bakery"],
  "targetLength": 2000,
  "tone": "warm and inviting",
  "additionalInstructions": "Include information about our weekend specials"
}

Hyperlocal Content (hyperlocal)¶

Create location-specific content with local relevance.

Required Fields: - type: "hyperlocal" - businessId: Your business identifier - location: Location object with address details

Location Object: - address: Full street address - lat: Latitude (optional but recommended) - lng: Longitude (optional but recommended) - nearbyLandmarks: Array of local landmarks (optional)

Example:

{
  "type": "hyperlocal",
  "businessId": "downtown-cafe",
  "location": {
    "address": "123 Main Street, Portland, OR 97201",
    "lat": 45.5152,
    "lng": -122.6784,
    "nearbyLandmarks": ["Pioneer Courthouse Square", "Powell's Books"]
  },
  "targetLength": 800
}

Google Business Profile Posts (gbp_post)¶

Generate engaging posts for Google Business Profile.

Required Fields: - type: "gbp_post" - businessId: Your business identifier

Optional Fields: - callToAction: Specific CTA text (max 1500 characters) - eventDetails: Event information object

Event Details Object: - title: Event name - date: Event date - time: Event time

Example:

{
  "type": "gbp_post",
  "businessId": "fitness-studio",
  "callToAction": "Join our morning yoga classes! Book now and save 20%",
  "eventDetails": {
    "title": "Sunrise Yoga Session",
    "date": "2024-03-15",
    "time": "7:00 AM"
  }
}

Job Status Workflow¶

Status Values¶

Progress Tracking¶

When status is "processing", additional fields provide progress information:

• progress: Completion percentage (0-100)
• stepsCompleted: Array of completed processing steps
• currentStep: Currently active processing step
• estimatedCompletionTime: Remaining seconds (approximate)

Processing Steps: 1. research - Keyword and topic research 2. outline - Content structure planning 3. writing - Content generation 4. editing - Quality review and optimization 5. finalization - Final formatting and validation

Error Handling¶

HTTP Status Codes¶

Error Response Format¶

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "problematic_field",
    "additionalInfo": "context"
  },
  "retryAfter": 60,
  "quotaResetDate": "2024-03-01"
}

Common Error Scenarios¶

Invalid API Key (401)¶

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Rate Limit Exceeded (429)¶

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 3600
}

Validation Error (422)¶

{
  "error": "Keywords are required for SEO articles",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "keywords"
  }
}

Rate Limits¶

Standard Limits¶

• Requests: 100 requests per hour
• Burst: 10 requests per minute
• Daily Jobs: 50 content generation jobs per day
• Concurrent Jobs: 3 active jobs maximum

Rate Limit Headers¶

Response headers indicate current usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 3600

Upgrading Limits¶

Contact our sales team for higher rate limits: - Professional: 500 requests/hour, 200 jobs/day - Enterprise: Custom limits and SLA

Webhooks (Coming Soon)¶

Webhook support is planned for v1.1 to provide real-time job status updates:

• Job completion notifications
• Error alerts
• Daily usage summaries

Best Practices¶

1. Polling Strategy¶

When checking job status, use exponential backoff:

import time
import requests

def poll_job_status(job_id, api_key):
    url = f"https://api.hgcontent.com/api/v1/jobs/{job_id}/status"
    headers = {"X-API-Key": api_key}

    delay = 5  # Start with 5 seconds
    max_delay = 60  # Cap at 1 minute

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()

        if data["status"] in ["completed", "failed", "cancelled"]:
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, max_delay)  # Exponential backoff

2. Error Handling¶

Always handle potential errors gracefully:

def create_content_job(request_data, api_key):
    try:
        response = requests.post(
            "https://api.hgcontent.com/api/v1/content/generate",
            json=request_data,
            headers={"X-API-Key": api_key}
        )

        if response.status_code == 429:
            # Rate limited - wait and retry
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            return create_content_job(request_data, api_key)

        response.raise_for_status()
        return response.json()

    except requests.RequestException as e:
        # Log error and handle appropriately
        print(f"API request failed: {e}")
        return None

3. Content Quality¶

For best results:

• SEO Articles: Provide 3-5 relevant keywords, specify target audience
• Hyperlocal: Include specific local landmarks and community details
• GBP Posts: Keep CTAs concise and action-oriented

4. Monitoring¶

Track your API usage:

• Monitor rate limit headers
• Log failed requests for analysis
• Set up alerts for quota thresholds
• Review content quality metrics

Interactive API Explorer¶

Explore the API interactively using our embedded OpenAPI specification:

{% swagger "../../openapi/hgcontent-api-v1.yaml" %}

SDKs and Libraries¶

Official SDKs¶

• Python: pip install hgcontent-api
• JavaScript/TypeScript: npm install @hgcontent/api-client

Code Examples¶

Python SDK¶

from hgcontent import HGContentClient

client = HGContentClient(api_key="your-api-key")

# Create SEO article
job = client.create_seo_article(
    business_id="biz-123",
    keywords=["local seo", "marketing"],
    target_length=1500
)

# Wait for completion
result = client.wait_for_completion(job.job_id)
print(result.content.title)

JavaScript SDK¶

import { HGContentClient } from '@hgcontent/api-client';

const client = new HGContentClient({ apiKey: 'your-api-key' });

// Create hyperlocal content
const job = await client.createHyperlocalContent({
  businessId: 'cafe-downtown',
  location: {
    address: '123 Main St, Portland, OR',
    nearbyLandmarks: ['Pioneer Square', 'Powell\'s Books']
  }
});

// Poll for completion
const result = await client.waitForCompletion(job.jobId);
console.log(result.content.title);

Troubleshooting¶

Common Issues¶

Jobs Stuck in "queued" Status¶

• Check system status page for service disruptions
• Verify API key has sufficient quota
• Try creating a new job after 5 minutes

Content Quality Issues¶

• Review and refine keywords/instructions
• Check business context is accurately specified
• Consider using additional instructions field

Rate Limiting Problems¶

• Implement exponential backoff in polling
• Space out job creation requests
• Consider upgrading to higher tier

Getting Help¶

• Documentation: Full API reference and guides
• Status Page: Real-time system status
• Support Email: api-support@hgcontent.com
• Community Forum: Developer discussions

Changelog¶

v1.0.0 (Current)¶

• Initial public release
• Support for 3 content types
• Job-based async processing
• API key authentication

Roadmap¶

• v1.1: Webhooks, additional content types
• v1.2: Bulk operations, advanced filtering
• v2.0: GraphQL support, real-time subscriptions

For the latest updates, follow our GitHub repository.