API Reference Overview

iContentForge provides a set of APIs to integrate automated content generation and publishing into your workflows. This overview covers the available endpoints, authentication methods, and general API conventions.

Base URL & Versioning

All API requests should be directed to your iContentForge instance's base URL. The primary API endpoints are versioned.

Base URL: https://app.icontentforge.com/api/v1

Authentication

Most API endpoints require authentication. iContentForge supports two primary methods:

1. Bearer Token (Recommended)

Use the API key generated within your iContentForge account settings as a Bearer token in the Authorization header.

curl -X GET 'https://app.icontentforge.com/api/v1/projects' \
  -H 'Authorization: Bearer YOUR_API_KEY_HERE'

2. API Key Query Parameter

For limited use cases, you can pass the API key as a query parameter. This is less secure and not recommended for server-side calls.

curl -X GET 'https://app.icontentforge.com/api/v1/projects?apiKey=YOUR_API_KEY_HERE'

Available APIs

Public Sitemap API

This API provides a dynamically generated XML sitemap for your published articles, perfect for search engine indexing. It is publicly accessible and does not require authentication.

Endpoint: GET /api/public/sitemap/:projectId

Example:

curl https://app.icontentforge.com/api/public/sitemap/proj_abc123def456

Webhook Receiver Specification

iContentForge can send webhook notifications to your configured endpoint (e.g., for article status updates). To verify the payload is from iContentForge, you must validate the request signature.

Signature Verification:

1. iContentForge signs each webhook payload using a secret specific to your project.
2. The signature is sent in the X-iCF-Signature header.
3. You must compute a hash using the HMAC-SHA256 algorithm with your project's webhook secret and the raw request body, then compare it to the provided signature.

Example Validation (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(req, secret) {
  const signature = req.headers['x-icf-signature'];
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(req.body)).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

General REST Publishing API

This is the core API for programmatically managing projects, keyword matrices, articles, and publishing. It uses Bearer Token authentication.

Common Endpoints:

• GET /projects - List your projects
• POST /projects/{id}/articles/generate - Generate articles from a keyword matrix
• GET /articles - List articles with filters (status, project)
• POST /articles/{id}/publish - Publish a specific article to a connected CMS

Rate Limits

To ensure service stability, API requests are subject to rate limits. Limits are applied per API key.

Exceeding the rate limit will result in a 429 Too Many Requests HTTP status code. The response headers include information about your current limit:

• X-RateLimit-Limit: Your request limit per minute.
• X-RateLimit-Remaining: Requests remaining in the current window.
• X-RateLimit-Reset: Time (Unix epoch seconds) when the limit resets.

Error Codes & Responses

The API uses standard HTTP status codes and returns error details in a JSON object.

Error Response Format:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested article could not be found.",
    "details": { "articleId": "art_xyz789" }
  }
}

Next Steps

• Learn how to manage your content programmatically in the REST API Guide.
• Set up real-time notifications by configuring Webhooks.
• Understand how to expose your sitemap to search engines using the Public Sitemap API.