Website Publishing API
[Last updated: October 21, 2026]
TTMSHub (a product of BR Digitals Inc) can publish articles to a business's own website, next to its social channels. The website adds three small HTTPS endpoints and creates a key; the business pastes the endpoint address and the key into TTMSHub under Manage → Channels → Connect Channel → Website.
This page is the full specification of version 1 of that interface. Everything is JSON over HTTPS, and TTMSHub is always the caller: the website never needs to call TTMSHub.
How It Works
The website chooses one base address for the API, its publishing API address, for example https://example.com/api/ttmshub/v1. TTMSHub adds a path to it for each operation:
| Request | When TTMSHub sends it |
|---|---|
GET {address}/site | When the website is connected or reconnected, and when TTMSHub checks it. |
POST {address}/posts | When a post scheduled for the website is published. |
DELETE {address}/posts/{id} | When someone deletes the published post from TTMSHub. |
In New post, the first line of the text becomes the article title and the rest its body; the first image is the cover.
Address and Network Rules
- The address must start with
https://, use the standard port (443) and have a valid certificate. - It must use a public domain name. IP addresses,
localhostand private names such as.localor.internalare refused, and every address the domain resolves to must be a public internet address. - No user name, password, query string or
#fragment. A trailing slash is removed, and the address can be at most 255 characters. - Answer directly: TTMSHub does not follow redirects, and reports a 3xx answer as an error.
- Answer within 20 seconds, with a response body of at most 1 MB.
Keys and Authentication
Every request carries the key as Authorization: Bearer <key> and identifies itself as User-Agent: TTMSHub-Website-Publisher/1 (+https://ttmshub.com).
- A key is 16 to 512 visible ASCII characters without spaces. Generate at least 32 random bytes (for example as base64url) and show the key once.
- Store only a hash of the key (for example SHA-256), compare it in constant time, and answer
401when the key is missing or wrong. - The key should only let TTMSHub publish and delete articles on this website, and the site owner should be able to revoke it.
- To replace a key, create a new one and choose Reconnect on the website channel in TTMSHub. The address stays the same.
TTMSHub keeps the key encrypted (AES-256-GCM) and never shows it again after it is saved.
Read the Site: GET /site
Answer 200with the website's name and public address. TTMSHub shows them on the channel. name and url are required; url and the optional iconUrl must use https://.
GET https://example.com/api/ttmshub/v1/site
Authorization: Bearer <key>
200 OK
{
"name": "Example Signs",
"url": "https://example.com",
"iconUrl": "https://example.com/icon-512.png"
}Publish an Article: POST /posts
The request body has these fields:
| Field | Value |
|---|---|
externalId | TTMSHub's id for this post on this website (up to 160 characters). It is the same on every retry: if an article with this externalId already exists, return it instead of creating a duplicate. |
title | The first line of the post, up to 200 characters. |
html | The body without the title, as escaped HTML that only uses <p>, <br> and <a href rel="noopener">. |
text | The full text as written, title line included (up to 100,000 characters). |
excerpt | A plain-text summary of up to 200 characters for article lists. |
images | Up to 10 { "url", "alt" } objects; the first is the cover and alt may be null. The URLs are signed and stop working after about 15 minutes, so download each image while handling the request and serve it from the website's own storage. |
link | The link attached to the post, or null. It is also the last paragraph of html. |
status | Always "publish": the article goes live right away. |
videos | Up to 1 { "url", "mimeType" } object (MP4, MOV or WebM, up to 100 MB), or an empty list. Like images, the URL is signed and expires, so download the video while handling the request, store it, and show it in the article with a video player. Answer within 45 seconds. |
Answer 200 or 201 with the article's id (a non-negative integer, or up to 255 letters, digits and . _ ~ : -) and, optionally, its public url. TTMSHub shows the link on the post.
POST https://example.com/api/ttmshub/v1/posts
Authorization: Bearer <key>
Content-Type: application/json; charset=utf-8
{
"externalId": "campaign-publish:7d9f6a52-1c0e-4c52-9d1f-0c2b8f6d2a10",
"title": "Our new LED storefront signs",
"html": "<p>We now build LED storefront signs.</p>\n<p><a href=\"https://example.com/led\" rel=\"noopener\">https://example.com/led</a></p>",
"text": "Our new LED storefront signs\n\nWe now build LED storefront signs.",
"excerpt": "We now build LED storefront signs.",
"images": [
{ "url": "https://ttmshub.com/api/media/…/content?expires=…&signature=…", "alt": "LED sign" }
],
"link": "https://example.com/led",
"status": "publish",
"videos": []
}
201 Created
{ "id": "1042", "url": "https://example.com/news/our-new-led-storefront-signs" }Delete an Article: DELETE /posts/{id}
The id is the one the website returned, URL-encoded. Answer 200 or 204 when the article is removed; 404 is also accepted and means it was already gone.
DELETE https://example.com/api/ttmshub/v1/posts/1042
Authorization: Bearer <key>
204 No ContentErrors, Retries and Duplicates
Send errors as JSON with a short, human-readable message (up to 300 characters are shown to the person who published the post):
422 Unprocessable Entity
{ "error": { "message": "The title is already used by another article." } }| Answer | What TTMSHub does |
|---|---|
401, 403 | Treats the key as refused: the post fails and the business is asked to reconnect the website with a new key. |
400, 409, 413, 422 | Fails the post and shows your message; it is not retried. |
404 | On /site: no API at this address. On delete: already deleted. |
429, 5xx | Retries later, honoring Retry-After (in seconds) when present. |
| No answer after the request was sent | Marks the post as unconfirmed instead of retrying, because the article may already exist. Answer quickly and use externalId so a later retry never creates a second article. |
Example Handler
A minimal outline in TypeScript for a Next.js website. Any language or framework works, as long as it follows the formats above.
// app/api/ttmshub/v1/[...path]/route.ts (Next.js). Store only the SHA-256 of the key.
import { createHash, timingSafeEqual } from 'node:crypto';
function authorized(request: Request): boolean {
const key = request.headers.get('authorization')?.replace(/^Bearer /, '') ?? '';
const expected = Buffer.from(process.env.TTMSHUB_KEY_SHA256 ?? '', 'hex');
const actual = createHash('sha256').update(key).digest();
return expected.length === 32 && timingSafeEqual(actual, expected);
}
export async function POST(request: Request): Promise<Response> {
if (!authorized(request)) {
return Response.json({ error: { message: 'Invalid key.' } }, { status: 401 });
}
const post = await request.json();
// 1. If an article with post.externalId exists, return it (TTMSHub may retry).
// 2. Download post.images and post.videos now (the URLs expire) and store them yourself.
// 3. Save the article (title, html, excerpt, cover image) as published.
const article = await saveArticle(post);
return Response.json({ id: String(article.id), url: article.url }, { status: 201 });
}Questions about connecting a website: info@brdigitals.com.
