Skip to content

HG Content – App & API Quick Guide

This quick guide unblocks users and developers today while the full MkDocs portal is being built.

For Users: Using the Application

Sign In, Verification, and Onboarding

  • If ENABLE_EMAIL_VERIFICATION=true, verify your email before app access. Use /auth/verify-email to resend verification or sign out.
  • If ENABLE_ONBOARDING=true, verified users without a client/org are guided to create or join a client. Super admins bypass membership only (not verification).

Configure OpenRouter Access

  • Go to Settings → API Keys.
  • Add your OpenRouter API key. This is now mandatory for all content generation.
  • The dashboard reads provider metadata from /api/providers/status (models, pricing, context windows). Use the filters in the Content form to pick the desired model (e.g., deepseek/...:free, openai/gpt-4o-mini).

Generate Content

  • Open the Content Request form (Dashboard → Content Generation).
  • Provide client, content type, topic, keywords, length, tone, and any extra instructions.
  • Submit. Jobs are queued in CPM and completed by OpenRouter. Free models (:free suffix) return $0.00 cost.

Monitor Results

  • Recent Jobs show provider badges and status.
  • Job Detail displays the content and metadata (provider, model, word count, etc.).

Troubleshooting

  • “OpenRouter API key is not configured” (503): Ensure you have an active OpenRouter key in Settings → API Keys.
  • Model dropdown empty: /api/providers/status may be unavailable—check CPM logs.
  • RLS insert denied: ensure a client_users row links your user to the client.

For Developers: API Quick Reference

Frontend (Next.js) API Routes

  • POST /api/content/generate
  • Auth: Supabase session (server-authenticated route).
  • Body: { client_id, content_type, topic, keywords, length?, tone?, llm_provider?, model?, provider_key_id? } (defaults llm_provider to openrouter).
  • Behavior: Validates client_users, resolves the client API key from CPM_CLIENT_API_KEYS, attaches the user’s OpenRouter key (provider_key_id), and forwards to CPM.

  • Response: 201 { job_id, status }.

  • GET /api/providers/status

  • Proxies CPM /providers/status and exposes all provider metadata (currently OpenRouter).

CPM (Content Production Module)

  • POST /generate (Bearer CPM API key)
  • Body: { content_type, prompt, client_id, llm_provider: 'openrouter', model, keywords?, length?, parameters?, user_id, provider_key_id }.

  • Response: 202 { job_id, status:'pending' }.

  • GET /jobs/{job_id} (Bearer)

  • Returns job status, provider/model metadata, SEO analysis, and generated content when completed.

  • GET /providers/status

  • Returns live provider catalogue (OpenRouter only in production).

External API v1

  • Base: http://localhost:8002/api/v1 (dev)

  • Auth: X-API-Key (dev override via EXTERNAL_TEST_API_KEY).

  • POST /content/generate

  • SEO Article: { type:'seo_article', businessId, keywords:[...], targetLength?, tone?, additionalInstructions?, urgency?, preferredModel?, llmProvider? }
  • Hyperlocal: { type:'hyperlocal', businessId, location:{ address? | lat+lng }, targetLength?, urgency?, preferredModel?, llmProvider? }
  • GBP Post: { type:'gbp_post', businessId, callToAction?, eventDetails?, urgency?, preferredModel?, llmProvider? }

  • Response: 201 { jobId, status, estimatedCompletionTime }.

  • GET /jobs/{jobId}/status → { jobId, status }

  • GET /jobs/{jobId}/content → { title, body, ... } when completed
  • GET /healthz and /api/v1/healthz → liveness

Errors & Status Codes

  • Validation: 400 (frontend), 422 (external)
  • Auth: 401; Permission: 403; Not found: 404; Provider: 5xx

Key Environment Variables

  • General: ENABLE_EMAIL_VERIFICATION, ENABLE_ONBOARDING
  • OpenRouter: OPENROUTER_API_KEY, OPENROUTER_DEFAULT_MODEL, OPENROUTER_ORIGIN, OPENROUTER_APP_NAME, OPENROUTER_TIMEOUT
  • Frontend→CPM auth: CPM_CLIENT_API_KEYS (JSON map of client_id → plaintext CPM key)
  • CPM service URL: CPM_SERVICE_URL
  • External API: EXTERNAL_TEST_API_KEY, EXTERNAL_TEST_CLIENT_ID, EXTERNAL_WORKER_ENABLED