CocoSEO
Integration Guide

Custom API Integration Guide

Connect CocoSEO to your custom CMS, headless platform, or any REST API to automatically publish your AI-generated blog posts.

Overview

The Custom API integration allows you to publish blog posts to any REST API endpoint. This is perfect for custom CMS platforms, headless systems, or any API that accepts blog post data.

What You Get

  • Automatic blog post publishing
  • Flexible request/response mapping
  • Custom authentication headers
  • Support for any HTTP method

Requirements

  • REST API endpoint
  • API key or authentication token
  • Endpoint accepts JSON payload
  • Returns JSON response

Configuration Options

Configure your custom API integration with these options.

Required Fields

apiUrl

The full URL of your API endpoint (e.g., https://api.example.com/posts)

apiKey

Your API key or authentication token for accessing the endpoint

Optional Fields

method

HTTP method to use (default: POST). Options: GET, POST, PUT, PATCH

endpoint

Additional endpoint path to append to apiUrl (e.g., /v1/articles). If your apiUrl already includes the full path, leave this empty.

headers

Additional custom headers to include in the request (e.g., { "X-Custom-Header": "value" })

bodyMapping

Map blog post fields to your API's expected field names. See examples below.

responseMapping

Map your API's response fields to extract post ID and URL. Supports dot notation for nested objects (e.g., data.id).

Request Body Mapping

Customize how blog post data is sent to your API.

By default, CocoSEO sends blog posts with these fields:

{
  "title": "Blog Post Title",
  "content": "Full blog post content...",
  "slug": "blog-post-title",
  "metaDescription": "SEO meta description",
  "excerpt": "SEO meta description",
  "tags": ["tag1", "tag2"]
}

excerpt is sent alongside metaDescription and mirrors the same value, so your API can use whichever field it expects.

If your API expects different field names, use bodyMapping to map them:

{
  "bodyMapping": {
    "title": "post_title",
    "content": "post_content",
    "slug": "post_slug",
    "metaDescription": "seo_description",
    "excerpt": "post_excerpt",
    "tags": "categories"
  }
}

This will send a request body like:

{
  "post_title": "Blog Post Title",
  "post_content": "Full blog post content...",
  "post_slug": "blog-post-title",
  "seo_description": "SEO meta description",
  "post_excerpt": "SEO meta description",
  "categories": ["tag1", "tag2"]
}

Response Mapping

Extract post ID and URL from your API's response.

CocoSEO needs to extract the post ID and URL from your API's response. By default, it looks for:

  • id or data.id for the post ID
  • url, link, or data.url for the post URL

If your API returns a different structure, use responseMapping. Supports dot notation for nested objects:

// Example API Response:
{
  "success": true,
  "data": {
    "article": {
      "id": "12345",
      "permalink": "https://example.com/posts/my-article"
    }
  }
}

// Response Mapping:
{
  "responseMapping": {
    "postId": "data.article.id",
    "postUrl": "data.article.permalink"
  }
}

Complete Examples

Real-world examples for different API structures.

Example 1: Simple API with Standard Fields

Your API accepts standard field names and returns a simple response:

{
  "apiUrl": "https://api.example.com/posts",
  "apiKey": "your-api-key-here",
  "method": "POST"
}

// API Response:
{
  "id": "123",
  "url": "https://example.com/posts/my-article"
}

Example 2: Custom Field Names

Your API uses different field names:

{
  "apiUrl": "https://api.example.com",
  "apiKey": "your-api-key-here",
  "endpoint": "/v1/articles",
  "method": "POST",
  "bodyMapping": {
    "title": "article_title",
    "content": "article_body",
    "slug": "article_slug",
    "metaDescription": "seo_meta",
    "tags": "article_tags"
  }
}

Example 3: Nested Response with Custom Headers

Your API requires custom headers and returns nested data:

{
  "apiUrl": "https://api.example.com",
  "apiKey": "your-api-key-here",
  "endpoint": "/content/posts",
  "method": "PUT",
  "headers": {
    "X-API-Version": "2.0",
    "X-Client-ID": "cocoseo"
  },
  "bodyMapping": {
    "title": "title",
    "content": "body",
    "slug": "slug"
  },
  "responseMapping": {
    "postId": "result.data.id",
    "postUrl": "result.data.permalink"
  }
}

// API Response:
{
  "result": {
    "data": {
      "id": "abc123",
      "permalink": "https://example.com/posts/my-article"
    }
  }
}

Example 4: Bearer Token Authentication

Your API uses Bearer token authentication:

{
  "apiUrl": "https://api.example.com/posts",
  "apiKey": "your-bearer-token-here",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-bearer-token-here"
  }
}

// Note: The apiKey will automatically be added as 
// both "Authorization: Bearer {apiKey}" and 
// "X-API-Key: {apiKey}" headers. You can override 
// this with custom headers if needed.

Authentication

How authentication works with your API.

By default, CocoSEO adds your API key in two ways:

  • Authorization: Bearer {apiKey}
  • X-API-Key: {apiKey}

If your API uses a different authentication method, you can override it using the headers field:

{
  "apiUrl": "https://api.example.com/posts",
  "apiKey": "your-key",
  "headers": {
    "X-Auth-Token": "your-key",
    "X-Custom-Header": "value"
  }
}

Security Note: Your API key is stored securely in our database. For production use, consider using environment variables or a secrets management service.

Testing Your Integration

Always test your integration before enabling auto-publish.

  1. Create your integration in the dashboard with your API configuration
  2. Click the "Test Connection" button to verify your API endpoint is reachable
  3. Publish a test blog post to ensure the request format matches your API's expectations
  4. Check the response mapping to ensure post ID and URL are extracted correctly
  5. Once verified, enable "Auto-Publish" to automatically publish all new blog posts

Tip: The test connection feature sends a simple request to verify connectivity. A 404 response is considered successful (the endpoint might not exist for testing), but any other error will be reported.

Troubleshooting

Common issues and how to fix them.

Error: Connection Failed

  • Verify your API URL is correct and accessible
  • Check if your API requires CORS headers
  • Ensure your API key is valid and has proper permissions

Error: Post ID/URL Not Found

  • Check your responseMapping configuration
  • Verify the response structure matches your mapping (use dot notation for nested objects)
  • Check the API response in the published post metadata

Error: Invalid Request Format

  • Review your bodyMapping configuration
  • Ensure field names match what your API expects
  • Check if your API requires additional fields not provided by default

Error: Authentication Failed

  • Verify your API key is correct
  • Check if your API uses a different authentication method and configure custom headers
  • Ensure your API key hasn't expired or been revoked

Best Practices

Follow these recommendations for a smooth integration.

  • Test First: Always test your integration with a single blog post before enabling auto-publish
  • Error Handling: Ensure your API returns proper HTTP status codes (200-299 for success, 400+ for errors)
  • Idempotency: If possible, make your API endpoint idempotent to handle retries safely
  • Rate Limiting: Be aware of your API's rate limits to avoid throttling
  • Logging: Check the published post metadata for detailed API responses and error messages
  • Security: Use HTTPS for all API endpoints and store API keys securely

Ready to Set Up Your Integration?

Go to your dashboard to create and configure your custom API integration.