jekcms's publish API connects to n8n with just a handful of workflow nodes — handling media uploads, setting categories, and following your publishing schedule. This article documents the exact node configuration: request format, authentication, error handling, and the tradeoffs between immediate, scheduled, and draft publishing.
The publish API endpoint is POST /api/v1/posts/publish-task. It accepts JSON with title, content, author_id, category, featured_image (a URL), and an optional scheduled_at ISO 8601 timestamp. The API key goes in the X-API-Key header. Successful creation returns the new post's ID and public URL.
Minimal n8n Workflow Structure
In n8n, the minimal working workflow has four nodes: an HTTP Request to fetch source content (from OpenAI, an RSS feed, or your own source), a Code node to format the payload, an HTTP Request to call the jekcms API, and an IF node to route errors to a Slack notification or retry queue.
Media Handling at Scale
Media handling deserves careful attention. When you pass a featured_image URL, jekcms fetches it synchronously during the API request, converts it to AVIF, and stores it locally. If the source URL is slow to respond, your entire API request blocks. For high-volume pipelines, pre-upload images to your jekcms install using the POST /api/v1/media/upload-from-url endpoint and pass the resulting media ID rather than a URL.
What Can Go Wrong
The most common failure mode in an automated publishing pipeline is a network timeout on the source content fetch — not an error from the jekcms API itself. Design your workflow assuming source fetches will occasionally time out: route those failures to a retry queue or a Slack alert rather than treating every failure as fatal. The force_duplicate: false default (see below) means a retried request cannot create a second copy of the same post, so it's safe to let n8n's retry mechanism run without babysitting it.
Complete n8n Node Configuration
Here is the exact HTTP Request node configuration for the publish call. The Content-Type header must be application/json, and the API key must go in the X-API-Key header — not as a query parameter, which was deprecated in v1.5.0 for security reasons.
// n8n HTTP Request Node Settings
Method: POST
URL: https://yoursite.com/api/v1/posts/publish-task
Authentication: None (handled via header)
Headers:
X-API-Key: {{ $credentials.jekcmsApiKey }}
Content-Type: application/json
Body (JSON):
{
"title": "{{ $json.title }}",
"content": "{{ $json.content }}",
"author_id": 2,
"category": "{{ $json.category }}",
"featured_image": "{{ $json.image_url }}",
"image_alt_text": "{{ $json.image_alt }}",
"scheduled_at": "{{ $json.publish_date }}"
}Error Handling With the IF Node
The IF node after the API call checks {{ $json.success }}. On failure, the error branch sends a Slack message containing the post title and the error message. For 409 duplicate errors specifically, we route to a separate branch that logs the duplicate but does not alert — duplicates are expected when reprocessing a content batch.
Scheduling and Publishing Cadence
jekcms supports three publishing modes through the API:
- Draft mode (the safer default): use the
/draftendpoint — the post is saved but stays invisible until someone reviews and publishes it from the admin panel. This is the right starting point for any new workflow or unproven content source, since nothing goes live without a human looking at it first. - Scheduled publish: pass an ISO 8601 timestamp (e.g.,
2026-03-01T09:00:00+03:00) — jekcms's cron publishes it at that time. Reasonable once you trust the source content and want predictable timing without reviewing every post individually. - Immediate publish: omit the
scheduled_atfield and the post goes live the moment the API call succeeds — there is no review step. If the source content is wrong, off-brand, or low-quality, it's live before anyone sees it. Treat this mode as something you graduate into after a workflow has proven itself with draft or scheduled publish, not a default to start with.
Whichever mode you choose, the decision belongs to you: jekcms doesn't force a review queue, but it also doesn't hide the risk of skipping one. For most teams, routing everything through draft or scheduled publish — and reviewing before it goes live — is the safer long-term habit, even once a pipeline is stable.
For SEO purposes, we stagger scheduled publications rather than publishing everything at once — for example, spacing posts at fixed intervals across the day using the Code node to assign sequential timestamps.
Category and Tag Automation
The API accepts category names as strings. If a category does not exist, jekcms creates it automatically with a generated slug. Tags work the same way — pass an array of strings in the tags field. This means your n8n workflow does not need to know the site's existing category IDs; it can simply pass the category name from the content source and let jekcms handle the lookup or creation.
Monitoring and Debugging
Every API request is logged to logs/api-{date}.log with the request method, endpoint, authentication result, response code, and execution time. For n8n debugging, enable the "Include Response Headers" option in the HTTP Request node — jekcms returns an X-Request-ID header that maps to the server log entry. When filing a support request, include this ID for faster log lookup.
- A text-only post typically publishes in well under a second.
- Passing a
featured_imageURL adds time for jekcms to fetch, convert to AVIF, and store the file — expect this to take several seconds, more on slow source servers or large images. - Maximum concurrent API requests per installation is configurable in
config/api.php(10 by default). - Rate limit: 120 requests per minute per API key (429 status code when exceeded).
Retry Strategy and Idempotency
Network failures are inevitable in any automated pipeline, so a retry strategy is worth building deliberately.
The jekcms publish API is idempotent when the force_duplicate: false default is in effect: if n8n retries a failed request and the post was actually created on the first attempt, the API returns a 409 duplicate response instead of creating a second copy. This means you can safely enable n8n's built-in retry mechanism (Settings > Retry on Fail) with a small number of attempts and a delay between retries without risking duplicate content.
For image-heavy workflows where a slow source server can push response times to ten seconds or more, increase the HTTP Request node's timeout accordingly and allow a couple of retries.
The combination of duplicate prevention at the API level and automatic retries at the workflow level means your content pipeline can recover from transient failures without manual intervention. The one failure mode retries can't fix is a permanently unreachable source URL — route those to manual review instead of retrying indefinitely.
