Flexpress
Flexpress APIInsights integration documentation
Integration guide
FLEXPRESS PLATFORM

Insights API documentation.

HMAC authentication, Make.com request signing, draft idempotency, endpoints, validation rules, testing, security controls and release checks.

API/api/v1Insights/api/v1/insightsAuthHMAC-SHA256Updated16 Aug 2026
SECTION 01

Purpose and scope

The Flexpress Insights API is a server-to-server integration surface for approved automation clients. The current design is intended primarily for Make.com, while retaining Airtable-compatible HMAC access for supporting workflows.

Feature boundary Authenticated GET can read the content pipeline. POST can create a new Draft and upload Insight images to the configured Bunny Storage zone. Publishing, updating, archiving, status changes and deletion remain manual Flexpress Web actions.
  • Dedicated API DTOs are returned instead of EF entities.
  • Administrative and sensitive data are excluded.
  • Payment endpoints and Flexpress Web Identity are outside this API scope.
SECTION 02

HMAC authentication

Protected Insights endpoints use the existing HmacReport authentication scheme.

Header Purpose
X-Flexpress-Client Configured integration client ID
X-Flexpress-Timestamp Current ISO-8601 timestamp
X-Flexpress-Nonce Unique value for this HTTP attempt
X-Flexpress-Signature Base64 HMAC-SHA256 signature
X-Correlation-ID Optional trace ID
Idempotency-Key Required for draft creation only

Canonical payload

METHOD
PATH_AND_QUERY
TIMESTAMP
NONCE
BODY_SHA256_HEX
CLIENT_ID

Sign the exact request path + encoded query string and the exact request body bytes. The default clock-skew allowance is ±5 minutes unless configured otherwise.

Empty body SHA-256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Scopes

Scope Access
insights:read List/detail/categories/authors/topics
insights:drafts:create Create a new Draft and upload Insight images
SECTION 03

Make.com integration flow

Make.com should generate the idempotency key for each logical draft operation. The same logical operation keeps the same key when retried.

  1. Receive the source item, for example an Airtable record.
  2. Set a stable key such as airtable-{recordId}.
  3. Serialize the JSON body once and sign the exact text that will be sent.
  4. Generate a new timestamp and a new nonce for this HTTP attempt.
  5. Calculate the body SHA-256 hash.
  6. Build the six-line canonical payload.
  7. Calculate Base64 HMAC-SHA256 using the Make.com secret.
  8. Send the HMAC headers, Idempotency-Key, and optionally X-Correlation-ID.
  9. On retry, reuse the idempotency key but generate a new timestamp, nonce and signature.
Nonce ≠ Idempotency-KeyThe nonce is unique for every HTTP request. The Idempotency-Key is stable across retries of the same logical create operation.
Situation Recommended key
One Airtable record → one Flexpress draft airtable-{recordId}
Network/timeout retry of same create Reuse the same key
Intentional second draft from same source Use a new version/operation suffix, e.g. airtable-{recordId}-v2
Current limitation Successful idempotency records are stored in process memory for 24 hours. They do not survive restart and are not shared across API instances.
SECTION 04

Idempotency and retries

Request Result
First POST with a new key 201 Created; new Draft; isReplay=false
Same body + same key 200 OK; same article; isReplay=true
Different body + same key 409 idempotency_conflict
Duplicate supplied slug 409 duplicate_slug
Idempotency-Key: airtable-recAbC123
SECTION 05

Endpoint reference

Method Route Scope Purpose
GET /api/v1/insights insights:read Search/filter/sort/paginate articles
GET /api/v1/insights/{id} insights:read Read one article by ID
GET /api/v1/insights/categories insights:read Active category lookup
GET /api/v1/insights/authors insights:read Active author lookup
GET /api/v1/insights/topics insights:read Active topic lookup
POST /api/v1/insights/drafts insights:drafts:create Create a Draft article
POST /api/v1/insights/images insights:drafts:create Upload an Insight image to Bunny Storage
GET /health Anonymous Health check
Intentionally absentNo slug lookup, update, publish, archive, status-change, or delete route.
SECTION 06

List filters and sorting

Parameter Default / type Rules
page 1 / integer Minimum 1
pageSize 25 / integer 1–100
search empty / string Max 250 chars
status empty / string Max 50 chars; exact filter
categoryId empty / integer Positive ID
topicId empty / integer Positive ID
authorId empty / integer Positive ID
createdFrom / createdTo empty / DateTime From ≤ To
updatedFrom / updatedTo empty / DateTime From ≤ To
publishedFrom / publishedTo empty / DateTime From ≤ To
sort newest / string See values below
newest
oldest
created-desc
created-asc
updated-desc
updated-asc
published-desc
published-asc
SECTION 07

Draft creation contract

POST /api/v1/insights/drafts always creates Draft; PublishedAt and UpdatedAt are null at creation. Unknown JSON members are rejected.

Required fields

Field Rules
title 3–250 chars
excerpt 10–1000 chars
insightCategoryId Active category
insightAuthorId Active author
contentType Required, max 100; DTO default Guide
bodyHtml 1–250,000 chars as submitted HTML/Markdown; non-empty after sanitisation and HTML-to-Markdown conversion

Optional fields

Field Rules
slug Max 300; normalises to unique non-empty slug if supplied
primarySearchQuery Max 250
isCornerstone Boolean
image URLs Max 1000, absolute HTTP/HTTPS
image alt text Max 250 each
seoTitle Max 250
metaDescription Max 500
topicIds Max 12 unique active topic IDs
productIds Max 20 unique public product IDs
primaryProductId Must also appear in productIds
relatedArticleIds Max 5 unique Published article IDs
Storage format Integration clients may submit HTML in bodyHtml. The API sanitises it, converts it to the Flexpress Markdown dialect, and stores only the converted Markdown in InsightArticle.BodyHtml.

The controller request-size limit is 512 KiB.

Example request

{
  "title": "Automation checklist for trade print teams",
  "slug": "",
  "excerpt": "A practical draft created by Make.com for editorial review.",
  "insightCategoryId": 1017,
  "insightAuthorId": 1,
  "contentType": "Guide",
  "primarySearchQuery": "trade print automation checklist",
  "isCornerstone": false,
  "heroImageUrl": "",
  "heroImageAltText": "",
  "thumbnailImageUrl": "",
  "thumbnailImageAltText": "",
  "socialImageUrl": "",
  "socialImageAltText": "",
  "seoTitle": "",
  "metaDescription": "",
  "bodyHtml": "<p>Draft content for human review.</p>",
  "topicIds": [],
  "productIds": [],
  "primaryProductId": null,
  "relatedArticleIds": []
}

Create response

{
  "id": 1097,
  "slug": "automation-checklist-for-trade-print-teams",
  "status": "Draft",
  "adminUrl": "/admin/insights/articles/edit/1097",
  "createdAt": "2026-08-06T20:35:04.4725934Z",
  "isReplay": false
}
SECTION 08

Insight image upload contract

POST /api/v1/insights/images accepts multipart/form-data and uploads the image directly to the configured Bunny Storage zone. The endpoint uses the existing insights:drafts:create scope and does not expose the Bunny Storage access key to the caller.

Storage boundary All uploads are written beneath insights/uploads. The optional folder value can add a safe subfolder, but cannot escape that root.
Form field Required Rules
file Yes Image file, maximum 5 MB. Allowed: AVIF, BMP, GIF, ICO, JPEG/JPG, PNG and WEBP.
folder No Optional safe subfolder beneath insights/uploads.

Signing multipart requests

The HMAC BODY_SHA256_HEX must be calculated from the exact serialized multipart request bytes, including the generated boundary and CRLF separators. The local API Test Console handles this automatically.

Do not sign only the raw image bytes The API verifies the hash of the complete HTTP request body, not only the uploaded file content.

201 response

{
  "fileName": "perfect-bound-book-20260816220531-a81f.jpg",
  "storagePath": "insights/uploads/perfect-bound-book-20260816220531-a81f.jpg",
  "url": "https://wowprinting.b-cdn.net/insights/uploads/perfect-bound-book-20260816220531-a81f.jpg",
  "contentType": "image/jpeg",
  "size": 284912
}

The returned url can be used for Insight image fields such as heroImageUrl, thumbnailImageUrl, and socialImageUrl.

SECTION 09

HTML sanitisation and Markdown storage

Submitted bodyHtml is treated as an integration input format, not the database storage format. The API sanitises incoming HTML first, then converts the safe result into the Markdown dialect consumed by the Flexpress Web MarkdownRenderer. Only that Markdown is saved.

No integration HTML is persistedFor example, <h2>Paper options</h2> is stored as ## Paper options, and <strong>Important</strong> is stored as **Important**.
Incoming HTMLStored Markdown
<h1>...</h1> to <h6>...</h6># ... to ###### ...
<p> / <br>Paragraph text / line break
<strong>, <b>**bold**
<em>, <i>*italic*
<del>, <s>~~deleted~~
<a href="...">[label](url)
<img>![alt](url) or Flexpress [image]{...} for figures
<blockquote>> quote
<ul> / <ol>Markdown unordered / ordered lists
<code> / <pre>Inline code / fenced code block
<table>Flexpress pipe table; HTML colspan becomes [colspan:n]

Unsupported presentation-only tags keep their safe text content where possible. Executable or unsafe elements such as scripts, styles, forms, objects and non-YouTube embeds are removed rather than converted.

Incoming: <h2>Artwork</h2><p>Use <strong>300dpi</strong> images.</p>
Stored:   ## Artwork

          Use **300dpi** images.
SECTION 10

Responses and errors

HTTP Meaning
200 Successful GET or idempotent replay
201 New Draft created or Insight image uploaded
400 Validation failed
401 HMAC authentication failed
403 Authenticated client lacks scope
404 Article ID not found
409 Idempotency/slug/database conflict
413 Upload request exceeds the configured request-size limit
429 Rate limit exceeded
500 Unexpected server failure
502 Bunny Storage did not accept the image upload
SECTION 11

Rate limiting

Operation Limit
Insights GET endpoints 120 requests/minute/client
Draft creation and image upload 20 requests/minute/client

Fixed-window limits are partitioned by the authenticated HMAC client claim.

SECTION 12

Correlation and audit logging

Logged Not logged
Correlation ID Client secret
Authenticated client ID HMAC signature
HTTP method Nonce/timestamp
Request path Request body
Status code Query values
Elapsed milliseconds Idempotency-Key

Safe caller correlation IDs are 1–64 characters using ASCII letters, digits, hyphen or underscore. Otherwise the API generates one.

SECTION 13

Local API Test Console

The custom test console is a local developer utility for signing and sending Insights API requests.

https://localhost:7221/api-console
  • Development environment only.
  • Loopback clients only; remote requests receive 404.
  • The client secret remains in current page memory and is not persisted.
  • The image-upload tester builds and hashes the exact multipart body bytes before sending the signed request.
  • The upload tester enforces the same 5 MB client-side limit before the request is sent.
  • Validation errors are short and do not expose JavaScript stack traces or source line numbers.
  • No-store caching and restrictive CSP/frame/referrer/MIME-sniffing headers are applied.
Do not publish the consoleKeep it as an internal developer utility and do not expose it as a production documentation surface.
SECTION 14

Secrets and environment rules

  • Separate client IDs/secrets for Make.com and Airtable.
  • Different secrets per environment.
  • Minimum required scopes only.
  • No real secrets in source control, URLs, query strings, logs, documentation, screenshots, or tickets.
  • The Bunny Storage AccessKey remains API-side configuration and is never returned to integration clients.
  • Use IP allowlists where reliable.
  • Disable unused clients and rotate secrets in a controlled deployment window.
SECTION 15

Release test checklist