GrowthAtlas Connector API v1

This document describes the GrowthAtlas Connector API v1 specification — the contract that all GrowthAtlas connectors (WordPress plugin, Laravel package, custom implementations) must implement.

GrowthAtlas uses this API to push content drafts to your website and to pull page/entity data for SEO analysis. As long as your site exposes these endpoints, GrowthAtlas can publish to it, regardless of platform.

Base URL

Connectors expose endpoints under a sub-path of your domain. The path prefix depends on the connector:

Authentication

All requests from GrowthAtlas include a Bearer token:

Authorization: Bearer <your-api-key>

Optionally, connectors can verify an HMAC-SHA256 signature for additional security:

X-GrowthAtlas-Signature: sha256=<hmac>

The HMAC is computed as HMAC-SHA256(secret, request_body). The signing secret is configured in the connector settings and in the GrowthAtlas dashboard.

Request Headers

GrowthAtlas always sends the following headers:

Response Envelope

All responses must be JSON. Successful responses return HTTP 200 or 201. Error responses return 4xx or 5xx.

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "message": "Human readable error message",
  "errors": { "field": ["validation error"] }
}

Endpoints

GET /health

Health check. Returns connector version and platform info.

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "connector": "wordpress",
    "connector_version": "1.0.0",
    "platform": "wordpress",
    "platform_version": "6.5.3",
    "php_version": "8.2.10",
    "growthatlas_api_version": "v1"
  }
}

GET /site-profile

Returns basic information about the website for context in content generation.

Response:

{
  "success": true,
  "data": {
    "name": "My Website",
    "url": "https://example.com",
    "description": "A brief description of the site",
    "language": "en",
    "platform": "wordpress",
    "timezone": "UTC",
    "post_types": ["post", "page", "product"],
    "taxonomies": ["category", "tag"]
  }
}

GET /pages

Returns a paginated list of published pages/posts for SEO analysis.

Query parameters:

Response:

{
  "success": true,
  "data": [
    {
      "url": "https://example.com/my-post",
      "title": "My Post Title",
      "meta_description": "Brief description",
      "h1": "My Post Title",
      "word_count": 1500,
      "published_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total": 350,
    "last_page": 4
  }
}

GET /entities

Returns a paginated list of entities (products, categories, locations, etc.) for topical authority building.

Query parameters:

Response:

{
  "success": true,
  "data": [
    {
      "id": "product-123",
      "type": "product",
      "name": "My Product",
      "slug": "my-product",
      "description": "Product description",
      "url": "https://example.com/products/my-product",
      "priority": 80,
      "metadata": {}
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total": 45,
    "last_page": 1
  }
}

POST /content-drafts

Receives a content draft from GrowthAtlas and publishes or saves it as a draft on your site.

Idempotency: The Idempotency-Key header is sent on every request. Connectors must check whether a post with the same growthatlas_draft_id already exists (via meta/custom field) and skip re-creating it. Instead, return the existing post's URL.

Request body:

{
  "growthatlas_draft_id": 123,
  "growthatlas_brief_id": 456,
  "title": "10 Best CRM Tools for Startups in 2025",
  "slug": "best-crm-tools-startups-2025",
  "excerpt": "A concise excerpt for the post.",
  "body": "## Introduction\n\nMarkdown body content...",
  "body_html": "<h2>Introduction</h2><p>HTML body content...</p>",
  "body_format": "markdown",
  "meta_title": "10 Best CRM Tools for Startups | My Site",
  "meta_description": "Discover the top CRM tools for startups in 2025.",
  "faq": [
    {
      "question": "What is a CRM?",
      "answer": "A CRM is..."
    }
  ],
  "schema_json": {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "10 Best CRM Tools"
  },
  "featured_image_url": "https://images.unsplash.com/photo-123",
  "featured_image_alt": "CRM dashboard illustration",
  "internal_links": [
    {
      "anchor": "email marketing tools",
      "url": "/email-marketing-guide"
    }
  ],
  "tags": ["crm", "startups", "productivity"],
  "categories": ["Software Reviews"],
  "language": "en",
  "publish_status": "draft",
  "target_keyword": "best crm for startups",
  "seo_score": 87,
  "source": "growthatlas"
}

Fields:

Response (success):

{
  "success": true,
  "data": {
    "external_id": "wp-post-4521",
    "url": "https://example.com/best-crm-tools-startups-2025",
    "status": "draft",
    "created": true
  }
}

Response (idempotent — already exists):

{
  "success": true,
  "data": {
    "external_id": "wp-post-4521",
    "url": "https://example.com/best-crm-tools-startups-2025",
    "status": "draft",
    "created": false
  }
}

Rate Limiting

GrowthAtlas respects Retry-After headers if returned. Connectors may limit requests per minute at their discretion. Recommended defaults:

• POST /content-drafts: 10 requests/minute
• Import endpoints: 60 requests/minute

Versioning

The current version is v1. Breaking changes will result in a new version (v2). Non-breaking additions (new optional fields) are made in-place without version bumps.

The version is included in all request paths and in the X-GrowthAtlas-Version header.

Security Checklist for Connector Implementors

• Validate Authorization: Bearer token using constant-time comparison
• Optionally verify X-GrowthAtlas-Signature HMAC-SHA256
• Implement idempotency for POST /content-drafts using growthatlas_draft_id
• Return proper HTTP status codes (200/201 for success, 4xx for errors)
• Never expose sensitive data in error messages
• Store API keys securely (encrypted, not in plain text)
• Implement slug conflict resolution (suffix or idempotent update)

Official Connectors