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.
- 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.
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.
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855Scopes
| Scope | Access |
|---|---|
| insights:read | List/detail/categories/authors/topics |
| insights:drafts:create | Create a new Draft and upload Insight images |
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.
- Receive the source item, for example an Airtable record.
- Set a stable key such as
airtable-{recordId}. - Serialize the JSON body once and sign the exact text that will be sent.
- Generate a new timestamp and a new nonce for this HTTP attempt.
- Calculate the body SHA-256 hash.
- Build the six-line canonical payload.
- Calculate Base64 HMAC-SHA256 using the Make.com secret.
- Send the HMAC headers,
Idempotency-Key, and optionallyX-Correlation-ID. - On retry, reuse the idempotency key but generate a new timestamp, nonce and signature.
| 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 |
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
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 |
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
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 |
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
}
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.
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.
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.
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.
<h2>Paper options</h2> is stored as ## Paper options, and <strong>Important</strong> is stored as **Important**.| Incoming HTML | Stored 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> |  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.
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 |
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.
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.
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.
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.