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:

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, localhost and private names such as .local or .internal are 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 401 when 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:

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 Content

Errors, 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." } }

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.