Update the blog

Embed

<a href="https://forumulate.com/reference/forumulate-api-blog-update"><img src="https://forumulate.com/reference/_api/public/orgs/046a9bc0-d530-43ae-9bae-af7945008cda/spaces/8042f004-e3d9-445f-b7a4-b6c1f86836e6/pages/14fd7cdf-0d35-4746-bfdc-c5f31bc3814c/social-card.svg?v=3e7ae33eec8b" alt="Update the blog" width="600" height="315"></a>

PATCHhttps://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}

Edits a post: its words, tags, cover, dates, credits and look. A partial update — a field you leave out keeps its value. bylines is the ordered list of credited names (guests with roles, or {author: key} from the registry) and byline the alias of its first entry; a tag is stored as a slug and the spelling you typed becomes its display name.

Requires token scope: write (the coarse method gate) for Atlas key (ak_), Personal Access Token (cft_) or OAuth (cfo_) auth — in addition to any catalog scope (GET /pats/scopes) the route’s capability needs. Session/cookie auth is governed by RBAC capabilities instead.

Parameters

orgIdstringpathrequired

spaceIdstringpathrequired

topicIdstringpathrequired

forumulate-versionstringheader

API version negotiation. Send forumulate-version: 2026-12-01 on every request from a new integration; it is optional only so that integrations written before versioning keep working. Each version includes everything before it:

Idempotency-Keystringheader

Makes this write safe to retry. Optional — send any unique string (a UUID is ideal) and the first request runs while its response is remembered under that key for 24 hours; an identical retry replays that same status and body instead of acting twice, so a timeout or a 5xx from the edge can be retried without creating a second row. A retry sent while the first request is still in flight is refused with 409. The key is scoped to the method and path, so the same key on a different endpoint is a different request. Error responses of 5xx are never cached — those retries re-run. A key is bound to the BODY it was first used with: reusing it with a different body is a 409 idempotency.key_reused, not a replay, because replaying would tell you a write landed that never ran. Generate one key per request, never per process or per session.

Request body application/json

content and markdown are ALTERNATIVES: send one of them. markdown is converted into the same block document content carries, so the resource that comes back is identical either way. Sending both is a 422 — nothing silently wins, because a client that sent the wrong field would otherwise see a 201 and the wrong body.

Example

{
  "title": "string",
  "slug": "string",
  "publishedAt": "2024-01-01T00:00:00Z",
  "byline": {
    "name": "string",
    "url": null,
    "avatarUrl": null
  },
  "author": "string",
  "bylines": [
    {
      "name": null,
      "role": null,
      "url": null,
      "avatarUrl": null,
      "bio": null,
      "author": null
    }
  ],
  "subtitle": "string",
  "content": {
    "type": "string",
    "content": []
  },
  "sections": {},
  "excerpt": "string",
  "coverUrl": "string",
  "coverAlt": "string",
  "series": "string",
  "socialImageUrl": "string",
  "tags": [
    "string"
  ],
  "seo": {
    "seoTitle": "string",
    "seoDescription": "string",
    "noindex": true,
    "canonicalUrl": "string",
    "socialImageUrl": "string"
  },
  "furtherReading": [
    {
      "label": "string",
      "href": "string"
    }
  ],
  "commentsEnabled": true,
  "onThisPage": "auto",
  "customization": {
    "customCss": null,
    "theme": null,
    "shareImageUrl": null,
    "ogTitle": null,
    "ogDescription": null,
    "twitterCard": null,
    "jsonLd": null
  },
  "editReason": "string",
  "pinned": true,
  "featured": true
}

Option 1

titlestring

slugstring

publishedAtstring

bylineobject

Show child parameters

namestringrequired

urlstring

avatarUrlstring

authorstring

bylinesobject[]

Every name this post credits, in order (at most 10, counting co-author accounts). Each is {name, role?, url?, avatarUrl?, bio?} or {author: <registry key>} (the space’s author registry fills the rest). byline is the alias of the first; null clears the list.

Show child parameters

namestring

rolestring

urlstring

avatarUrlstring

biostring

authorstring

subtitlestring

contentobjectrequired

Show child parameters

typestringrequired

contentobject[]

= []

sectionsobject

Markdown per section of the piece, keyed by the section key its shape declares. A BLOG article ships two, BOTH REQUIRED: standfirst (the line listings and link previews show) and body (the post). A space can add or rename its own — the keys for one are at GET /space-types/{type}/slots (and the space’s own shape). Combined with markdown, which follows the sections as ordinary prose.

excerptstring

coverUrlstring

coverAltstring

seriesstring

socialImageUrlstring

tagsstring[]

seoobject

Show child parameters

seoTitlestring

seoDescriptionstring

noindexboolean

canonicalUrlstring

socialImageUrlstring

furtherReadingobject[]

Show child parameters

labelstringrequired

hrefstringrequired

commentsEnabledboolean

onThisPagestring

Whether THIS piece carries the "on this page" rail: auto (the surface default), always or never. Beats the space theme’s onThisPage; null clears it back to the space’s.

customizationobject

This piece’s own look and share card: customCss, theme (partial), shareImageUrl, ogTitle, ogDescription, twitterCard, jsonLd. Keys merge on write; null clears one key, or every key when sent for the whole object.

Show child parameters

customCssstring

CSS for THIS piece only, after the space theme so it wins. Sanitised and scoped to the reader exactly like the space customCss (@import dropped, no way out of the <style>).

themeobject

A partial theme for this piece — colours, palettes, fonts, typography, colorScheme, components, contentWidth, layout, motion, and (on a blog post) post — layered over the space’s (which is over the site’s). On a post, release, event or legal document PATCH it MERGES key by key like the space theme’s PATCH, and null clears at any depth ({"paletteDark": null}); a page’s metadata replaces it whole. Unknown keys are refused by name. null clears all of it.

Show child parameters

primaryColorstring

accentColorstring

paletteobject

paletteDarkobject

fontstring

customFontFamilystring

headingFontFamilystring

bodyFontFamilystring

monoFontFamilystring

colorSchemestring

contentWidthstring

layoutobject

componentsobject

motionobject

changelogobject

typographyobject

postobject

shareImageUrlstring

The og:image / twitter:image for this piece, separate from its cover. Wins over the cover and over the generated social card.

ogTitlestring

og:title / twitter:title.

ogDescriptionstring

og:description / twitter:description.

twitterCardstring

summary (thumbnail) or summary_large_image (the default).

jsonLdstring

Structured data for this piece, as JSON (object or array of objects). Replaces the automatic markup on this piece (Article/BlogPosting, Event, DiscussionForumPosting/QAPage, the roadmap item’s Article). null restores the automatic one.

editReasonstring

pinnedboolean

featuredboolean

{
  "title": "string",
  "slug": "string",
  "publishedAt": "2024-01-01T00:00:00Z",
  "byline": {
    "name": "string",
    "url": "string",
    "avatarUrl": "string"
  },
  "author": "string",
  "bylines": [
    {
      "name": "string",
      "role": "string",
      "url": null,
      "avatarUrl": null,
      "bio": "string",
      "author": "string"
    }
  ],
  "subtitle": "string",
  "content": {
    "type": "string",
    "content": []
  },
  "sections": {},
  "excerpt": "string",
  "coverUrl": "string",
  "coverAlt": "string",
  "series": "string",
  "socialImageUrl": "string",
  "tags": [
    "string"
  ],
  "seo": {
    "seoTitle": "string",
    "seoDescription": "string",
    "noindex": true,
    "canonicalUrl": "string",
    "socialImageUrl": "string"
  },
  "furtherReading": [
    {
      "label": "string",
      "href": "string"
    }
  ],
  "commentsEnabled": true,
  "onThisPage": "auto",
  "customization": {
    "customCss": "string",
    "theme": {
      "primaryColor": null,
      "accentColor": null,
      "palette": null,
      "paletteDark": null,
      "font": null,
      "customFontFamily": null,
      "headingFontFamily": null,
      "bodyFontFamily": null,
      "monoFontFamily": null,
      "colorScheme": null,
      "contentWidth": null,
      "layout": null,
      "components": null,
      "motion": null,
      "changelog": null,
      "typography": null,
      "post": null
    },
    "shareImageUrl": null,
    "ogTitle": "string",
    "ogDescription": "string",
    "twitterCard": "summary",
    "jsonLd": "string"
  },
  "editReason": "string",
  "pinned": true,
  "featured": true
}

Option 2

titlestring

slugstring

publishedAtstring

bylineobject

Show child parameters

namestringrequired

urlstring

avatarUrlstring

authorstring

bylinesobject[]

Show child parameters

namestring

rolestring

urlstring

avatarUrlstring

biostring

authorstring

subtitlestring

markdownstringrequired

The body as Markdown (CommonMark + tables/task lists), converted server-side. Alternative to content. Blocks beyond plain Markdown (callouts, tabs, cards, steppers, columns, buttons, …) are written as :::name{attrs} directives — every directive, its attributes and how it closes: GET /docs/markdown-dialect. Up to 2,000,000 characters of Markdown — the same ceiling the importer, the create and the update doors all use, so an imported page can always be written back.

sectionsobject

excerptstring

coverUrlstring

coverAltstring

seriesstring

socialImageUrlstring

tagsstring[]

seoobject

Show child parameters

seoTitlestring

seoDescriptionstring

noindexboolean

canonicalUrlstring

socialImageUrlstring

furtherReadingobject[]

Show child parameters

labelstringrequired

hrefstringrequired

commentsEnabledboolean

onThisPagestring

Whether THIS piece carries the "on this page" rail: auto (the surface default), always or never. Beats the space theme’s onThisPage; null clears it back to the space’s.

customizationobject

Show child parameters

customCssstring

CSS for THIS piece only, after the space theme so it wins. Sanitised and scoped to the reader exactly like the space customCss (@import dropped, no way out of the <style>).

themeobject

Show child parameters

primaryColorstring

accentColorstring

paletteobject

paletteDarkobject

fontstring

customFontFamilystring

headingFontFamilystring

bodyFontFamilystring

monoFontFamilystring

colorSchemestring

contentWidthstring

layoutobject

componentsobject

motionobject

changelogobject

typographyobject

postobject

shareImageUrlstring

The og:image / twitter:image for this piece, separate from its cover. Wins over the cover and over the generated social card.

ogTitlestring

og:title / twitter:title.

ogDescriptionstring

og:description / twitter:description.

twitterCardstring

summary (thumbnail) or summary_large_image (the default).

jsonLdstring

editReasonstring

pinnedboolean

featuredboolean

{
  "title": "string",
  "slug": "string",
  "publishedAt": "2024-01-01T00:00:00Z",
  "byline": {
    "name": "string",
    "url": "string",
    "avatarUrl": "string"
  },
  "author": "string",
  "bylines": [
    {
      "name": "string",
      "role": "string",
      "url": null,
      "avatarUrl": null,
      "bio": "string",
      "author": "string"
    }
  ],
  "subtitle": "string",
  "markdown": "string",
  "sections": {},
  "excerpt": "string",
  "coverUrl": "string",
  "coverAlt": "string",
  "series": "string",
  "socialImageUrl": "string",
  "tags": [
    "string"
  ],
  "seo": {
    "seoTitle": "string",
    "seoDescription": "string",
    "noindex": true,
    "canonicalUrl": "string",
    "socialImageUrl": "string"
  },
  "furtherReading": [
    {
      "label": "string",
      "href": "string"
    }
  ],
  "commentsEnabled": true,
  "onThisPage": "auto",
  "customization": {
    "customCss": "string",
    "theme": {
      "primaryColor": null,
      "accentColor": null,
      "palette": null,
      "paletteDark": null,
      "font": null,
      "customFontFamily": null,
      "headingFontFamily": null,
      "bodyFontFamily": null,
      "monoFontFamily": null,
      "colorScheme": null,
      "contentWidth": null,
      "layout": null,
      "components": null,
      "motion": null,
      "changelog": null,
      "typography": null,
      "post": null
    },
    "shareImageUrl": null,
    "ogTitle": "string",
    "ogDescription": "string",
    "twitterCard": "summary",
    "jsonLd": "string"
  },
  "editReason": "string",
  "pinned": true,
  "featured": true
}

Code samples

cURL

curl -X PATCH "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}" \
  -H "forumulate-version: <value>" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/json" \
  -d '{"title":"string","slug":"string","publishedAt":"2024-01-01T00:00:00Z","byline":{"name":"string","url":null,"avatarUrl":null},"author":"string","bylines":[{"name":null,"role":null,"url":null,"avatarUrl":null,"bio":null,"author":null}],"subtitle":"string","content":{"type":"string","content":[]},"sections":{},"excerpt":"string","coverUrl":"string","coverAlt":"string","series":"string","socialImageUrl":"string","tags":["string"],"seo":{"seoTitle":"string","seoDescription":"string","noindex":true,"canonicalUrl":"string","socialImageUrl":"string"},"furtherReading":[{"label":"string","href":"string"}],"commentsEnabled":true,"onThisPage":"auto","customization":{"customCss":null,"theme":null,"shareImageUrl":null,"ogTitle":null,"ogDescription":null,"twitterCard":null,"jsonLd":null},"editReason":"string","pinned":true,"featured":true}'

TypeScript

const res = await fetch('https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}', {
  method: 'PATCH',
  headers: {
    'forumulate-version': '<value>',
    'Idempotency-Key': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"title":"string","slug":"string","publishedAt":"2024-01-01T00:00:00Z","byline":{"name":"string","url":null,"avatarUrl":null},"author":"string","bylines":[{"name":null,"role":null,"url":null,"avatarUrl":null,"bio":null,"author":null}],"subtitle":"string","content":{"type":"string","content":[]},"sections":{},"excerpt":"string","coverUrl":"string","coverAlt":"string","series":"string","socialImageUrl":"string","tags":["string"],"seo":{"seoTitle":"string","seoDescription":"string","noindex":true,"canonicalUrl":"string","socialImageUrl":"string"},"furtherReading":[{"label":"string","href":"string"}],"commentsEnabled":true,"onThisPage":"auto","customization":{"customCss":null,"theme":null,"shareImageUrl":null,"ogTitle":null,"ogDescription":null,"twitterCard":null,"jsonLd":null},"editReason":"string","pinned":true,"featured":true}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "PATCH",
    "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}",
    headers={
    "forumulate-version": "<value>",
    "Idempotency-Key": "<value>",
    "Content-Type": "application/json",
    },
    json={"title": "string", "slug": "string", "publishedAt": "2024-01-01T00:00:00Z", "byline": {"name": "string", "url": None, "avatarUrl": None}, "author": "string", "bylines": [{"name": None, "role": None, "url": None, "avatarUrl": None, "bio": None, "author": None}], "subtitle": "string", "content": {"type": "string", "content": []}, "sections": {}, "excerpt": "string", "coverUrl": "string", "coverAlt": "string", "series": "string", "socialImageUrl": "string", "tags": ["string"], "seo": {"seoTitle": "string", "seoDescription": "string", "noindex": True, "canonicalUrl": "string", "socialImageUrl": "string"}, "furtherReading": [{"label": "string", "href": "string"}], "commentsEnabled": True, "onThisPage": "auto", "customization": {"customCss": None, "theme": None, "shareImageUrl": None, "ogTitle": None, "ogDescription": None, "twitterCard": None, "jsonLd": None}, "editReason": "string", "pinned": True, "featured": True},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("PATCH", "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}", strings.NewReader(`{"title":"string","slug":"string","publishedAt":"2024-01-01T00:00:00Z","byline":{"name":"string","url":null,"avatarUrl":null},"author":"string","bylines":[{"name":null,"role":null,"url":null,"avatarUrl":null,"bio":null,"author":null}],"subtitle":"string","content":{"type":"string","content":[]},"sections":{},"excerpt":"string","coverUrl":"string","coverAlt":"string","series":"string","socialImageUrl":"string","tags":["string"],"seo":{"seoTitle":"string","seoDescription":"string","noindex":true,"canonicalUrl":"string","socialImageUrl":"string"},"furtherReading":[{"label":"string","href":"string"}],"commentsEnabled":true,"onThisPage":"auto","customization":{"customCss":null,"theme":null,"shareImageUrl":null,"ogTitle":null,"ogDescription":null,"twitterCard":null,"jsonLd":null},"editReason":"string","pinned":true,"featured":true}`))
	req.Header.Set("forumulate-version", "<value>")
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['forumulate-version: <value>', 'Idempotency-Key: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"title":"string","slug":"string","publishedAt":"2024-01-01T00:00:00Z","byline":{"name":"string","url":null,"avatarUrl":null},"author":"string","bylines":[{"name":null,"role":null,"url":null,"avatarUrl":null,"bio":null,"author":null}],"subtitle":"string","content":{"type":"string","content":[]},"sections":{},"excerpt":"string","coverUrl":"string","coverAlt":"string","series":"string","socialImageUrl":"string","tags":["string"],"seo":{"seoTitle":"string","seoDescription":"string","noindex":true,"canonicalUrl":"string","socialImageUrl":"string"},"furtherReading":[{"label":"string","href":"string"}],"commentsEnabled":true,"onThisPage":"auto","customization":{"customCss":null,"theme":null,"shareImageUrl":null,"ogTitle":null,"ogDescription":null,"twitterCard":null,"jsonLd":null},"editReason":"string","pinned":true,"featured":true}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}')
req = Net::HTTP::Patch.new(uri)
req['forumulate-version'] = '<value>'
req['Idempotency-Key'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"title":"string","slug":"string","publishedAt":"2024-01-01T00:00:00Z","byline":{"name":"string","url":null,"avatarUrl":null},"author":"string","bylines":[{"name":null,"role":null,"url":null,"avatarUrl":null,"bio":null,"author":null}],"subtitle":"string","content":{"type":"string","content":[]},"sections":{},"excerpt":"string","coverUrl":"string","coverAlt":"string","series":"string","socialImageUrl":"string","tags":["string"],"seo":{"seoTitle":"string","seoDescription":"string","noindex":true,"canonicalUrl":"string","socialImageUrl":"string"},"furtherReading":[{"label":"string","href":"string"}],"commentsEnabled":true,"onThisPage":"auto","customization":{"customCss":null,"theme":null,"shareImageUrl":null,"ogTitle":null,"ogDescription":null,"twitterCard":null,"jsonLd":null},"editReason":"string","pinned":true,"featured":true}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/blog/{topicId}"))
    .header("forumulate-version", "<value>")
    .header("Idempotency-Key", "<value>")
    .header("Content-Type", "application/json")
    .method("PATCH", BodyPublishers.ofString("{\"title\":\"string\",\"slug\":\"string\",\"publishedAt\":\"2024-01-01T00:00:00Z\",\"byline\":{\"name\":\"string\",\"url\":null,\"avatarUrl\":null},\"author\":\"string\",\"bylines\":[{\"name\":null,\"role\":null,\"url\":null,\"avatarUrl\":null,\"bio\":null,\"author\":null}],\"subtitle\":\"string\",\"content\":{\"type\":\"string\",\"content\":[]},\"sections\":{},\"excerpt\":\"string\",\"coverUrl\":\"string\",\"coverAlt\":\"string\",\"series\":\"string\",\"socialImageUrl\":\"string\",\"tags\":[\"string\"],\"seo\":{\"seoTitle\":\"string\",\"seoDescription\":\"string\",\"noindex\":true,\"canonicalUrl\":\"string\",\"socialImageUrl\":\"string\"},\"furtherReading\":[{\"label\":\"string\",\"href\":\"string\"}],\"commentsEnabled\":true,\"onThisPage\":\"auto\",\"customization\":{\"customCss\":null,\"theme\":null,\"shareImageUrl\":null,\"ogTitle\":null,\"ogDescription\":null,\"twitterCard\":null,\"jsonLd\":null},\"editReason\":\"string\",\"pinned\":true,\"featured\":true}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 Success.

Example

{
  "article": {
    "answerCount": 0,
    "answerPostId": "string",
    "assignedGroupId": "string",
    "assigneeId": "string",
    "authorAvatarSeed": "string",
    "authorAvatarUrl": "string",
    "authorId": "string",
    "authorKind": "anonymous",
    "authorName": "string",
    "authorPoints": 0,
    "authors": [
      {
        "name": "string",
        "userId": "string"
      }
    ],
    "authorTitle": "string",
    "authorUsername": "string",
    "bookmarked": true,
    "byline": {
      "avatarUrl": "string",
      "name": "string",
      "url": "string"
    },
    "bylines": [
      {
        "author": null,
        "avatarUrl": null,
        "bio": null,
        "handle": "string",
        "name": "string",
        "role": null,
        "url": null,
        "userId": null
      }
    ],
    "categoryId": "string",
    "commentsEnabled": true,
    "contentChangedAt": "2024-01-01T00:00:00Z",
    "coverUrl": "string",
    "customization": {
      "customCss": "string",
      "jsonLd": "string",
      "ogDescription": "string",
      "ogTitle": "string",
      "shareImageUrl": "string",
      "theme": {
        "accentColor": null,
        "bodyFontFamily": null,
        "changelog": null,
        "colorScheme": null,
        "components": null,
        "contentWidth": null,
        "customFontFamily": null,
        "font": null,
        "headingFontFamily": null,
        "layout": null,
        "monoFontFamily": null,
        "motion": null,
        "palette": null,
        "paletteDark": null,
        "post": null,
        "primaryColor": null,
        "typography": null
      },
      "twitterCard": "summary"
    },
    "deletedAt": "2024-01-01T00:00:00Z",
    "excerpt": "string",
    "expiresAt": "2024-01-01T00:00:00Z",
    "featured": true,
    "featuredLink": "string",
    "fields": {},
    "firstImageUrl": "string",
    "furtherReading": [
      {
        "href": "string",
        "label": "string"
      }
    ],
    "id": "string",
    "isNew": true,
    "kind": "ARTICLE",
    "lastActivityAt": "2024-01-01T00:00:00Z",
    "lastPostedAt": "string",
    "lastPosterName": "string",
    "likeCount": 0,
    "linkedTopics": [
      {
        "createdAt": "2024-01-01T00:00:00Z",
        "fromPostNumber": 0,
        "id": "string",
        "slug": "string",
        "title": "string"
      }
    ],
    "listed": true,
    "mergedIntoId": "string",
    "number": 0,
    "onThisPage": "always",
    "op": {
      "actionCode": "string",
      "actionData": {},
      "authorAvatarSeed": "string",
      "authorAvatarUrl": "string",
      "authorBadges": [
        {
          "icon": null,
          "name": null,
          "slug": null
        }
      ],
      "authorBadgeTiers": {
        "bronze": 0,
        "gold": 0,
        "silver": 0
      },
      "authorFlair": {
        "bgColor": null,
        "color": null,
        "icon": null,
        "label": "string"
      },
      "authorId": "string",
      "authorKind": "anonymous",
      "authorName": "string",
      "authorPoints": 0,
      "authorRole": "moderator",
      "authorStatus": {
        "emoji": null,
        "message": null
      },
      "authorTitle": "string",
      "authorTrust": 0,
      "authorUsername": "string",
      "content": {
        "type": "doc",
        "content": [
          {
            "type": "heading",
            "attrs": {
              "level": 1
            },
            "content": [
              {
                "type": "text",
                "text": "Getting started"
              }
            ]
          },
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Install the SDK, then create your first page."
              }
            ]
          },
          {
            "type": "codeBlock",
            "attrs": {
              "language": "bash"
            },
            "content": [
              {
                "type": "text",
                "text": "npm i @forumulate/sdk"
              }
            ]
          }
        ]
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "editedAt": "2024-01-01T00:00:00Z",
      "flagCount": 0,
      "id": "string",
      "isOp": true,
      "likeCount": 0,
      "parentAuthorName": "string",
      "parentPostId": "string",
      "parentPostNumber": 0,
      "postNumber": 0,
      "reactions": {},
      "status": "hidden",
      "voteCount": 0,
      "whisper": true,
      "wiki": true
    },
    "pinned": true,
    "pinnedGlobally": true,
    "pinnedUntil": "2024-01-01T00:00:00Z",
    "posters": [
      {
        "avatarSeed": "string",
        "avatarUrl": null,
        "kind": "anonymous",
        "name": "string",
        "role": "frequent",
        "username": null
      }
    ],
    "promotedPage": {
      "id": "string",
      "spaceId": "string",
      "title": "string"
    },
    "promotedPageId": "string",
    "publishedAt": "2024-01-01T00:00:00Z",
    "readingMinutes": 0,
    "releaseVersion": "string",
    "replies": [
      {
        "actionCode": null,
        "actionData": null,
        "authorAvatarSeed": "string",
        "authorAvatarUrl": "string",
        "authorBadges": [
          null
        ],
        "authorBadgeTiers": {
          "bronze": null,
          "gold": null,
          "silver": null
        },
        "authorFlair": {
          "bgColor": null,
          "color": null,
          "icon": null,
          "label": null
        },
        "authorId": null,
        "authorKind": "anonymous",
        "authorName": "string",
        "authorPoints": 0,
        "authorRole": "moderator",
        "authorStatus": {
          "emoji": null,
          "message": null
        },
        "authorTitle": "string",
        "authorTrust": 0,
        "authorUsername": "string",
        "content": {
          "type": "doc",
          "content": [
            {
              "type": "heading",
              "attrs": {
                "level": 1
              },
              "content": [
                {
                  "type": "text",
                  "text": "Getting started"
                }
              ]
            },
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Install the SDK, then create your first page."
                }
              ]
            },
            {
              "type": "codeBlock",
              "attrs": {
                "language": "bash"
              },
              "content": [
                {
                  "type": "text",
                  "text": "npm i @forumulate/sdk"
                }
              ]
            }
          ]
        },
        "createdAt": "2024-01-01T00:00:00Z",
        "editedAt": null,
        "flagCount": 0,
        "id": "string",
        "isOp": true,
        "likeCount": 0,
        "parentAuthorName": "string",
        "parentPostId": null,
        "parentPostNumber": 0,
        "postNumber": 0,
        "reactions": {},
        "status": "hidden",
        "voteCount": 0,
        "whisper": true,
        "wiki": true
      }
    ],
    "replyCount": 0,
    "replyPreviews": [
      {
        "author": "string",
        "authorAvatar": null,
        "authorSeed": "string",
        "text": "string"
      }
    ],
    "review": {
      "note": "string",
      "requestedAt": "2024-01-01T00:00:00Z",
      "requestedBy": "string",
      "reviewedAt": "2024-01-01T00:00:00Z",
      "reviewedBy": "string",
      "state": "approved"
    },
    "roadmapStatus": "string",
    "scheduledFor": "2024-01-01T00:00:00Z",
    "seo": {
      "noindex": true,
      "seoDescription": "string",
      "seoTitle": "string"
    },
    "series": "string",
    "shippedTopicIds": [
      "string"
    ],
    "slowModeSeconds": 0,
    "slug": "string",
    "state": "ARCHIVED",
    "status": "archived",
    "subtitle": "string",
    "tagInfo": [
      {
        "color": null,
        "colorDark": null,
        "coverUrl": null,
        "description": null,
        "gradient": null,
        "icon": "string",
        "label": "string",
        "pagePalette": null,
        "pageScheme": "dark",
        "slug": "string",
        "textColor": null,
        "textColorDark": null
      }
    ],
    "tags": [
      "string"
    ],
    "title": "string",
    "unread": 0,
    "updatedAt": "2024-01-01T00:00:00Z",
    "viewCount": 0,
    "voteCount": 0
  },
  "warnings": [
    "string"
  ]
}

Schema

articleobjectrequired

Show child parameters

answerCountnumber

answerPostIdstringrequired

assignedGroupIdstringrequired

assigneeIdstringrequired

authorAvatarSeedstring

authorAvatarUrlstring

authorIdstringrequired

authorKindstring

authorNamestringrequired

authorPointsnumber

authorsobject[]required

Show child parameters

namestringrequired

userIdstringrequired

authorTitlestring

authorUsernamestring

bookmarkedboolean

bylineBylinerequired

Show child parameters

avatarUrlstring

namestring

urlstring

bylinesBylineView[]

Show child parameters

authorstringrequired

avatarUrlstringrequired

biostringrequired

handlestring

namestringrequired

rolestringrequired

urlstringrequired

userIdstringrequired

categoryIdstringrequired

commentsEnabledbooleanrequired

contentChangedAtstring

coverUrlstringrequired

customizationPieceCustomizationrequired

Show child parameters

customCssstring

jsonLdstring

ogDescriptionstring

ogTitlestring

shareImageUrlstring

themeobject

twitterCardstring

summary | summary_large_image

deletedAtstring

excerptstringrequired

expiresAtstring

featuredbooleanrequired

featuredLinkstringrequired

fieldsobjectrequired

firstImageUrlstring

furtherReadingobject[]required

Show child parameters

hrefstringrequired

labelstringrequired

idstringrequired

isNewboolean

kindstringrequired

ARTICLE | DISCUSSION | FEATURE | QUESTION | RELEASE

lastActivityAtstringrequired

lastPostedAtstring

lastPosterNamestring

likeCountnumber

linkedTopicsLinkedTopic[]required

Show child parameters

createdAtstringrequired

fromPostNumbernumberrequired

idstringrequired

slugstringrequired

titlestringrequired

listedbooleanrequired

mergedIntoIdstringrequired

numbernumberrequired

onThisPagestringrequired

always | auto | never

opobjectrequired

Show child parameters

actionCodestringrequired

actionDataobjectrequired

400 The request could not be understood — a malformed header, path or query value (request.malformed). A value that was understood but is not acceptable is a 422 validation.failed.

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

401 No credential, or one that is expired or revoked (auth.required). Send a Bearer token or the session cookie.

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

403 Authenticated, and not allowed — always rbac.forbidden, whether what is missing is the capability, the token scope, or a resource the token is pinned away from. The message names the capability and, for a scope refusal, the scopes that would grant it. A refusal because of the PLAN is a 402 with quota.exceeded, not this.

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

404 No such thing — one of the ids in the path does not resolve, or resolves to something this caller may not see (*.not_found).

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

409 Refused because of the state this already is in — a name or slug already taken, a resource that already exists, or a precondition on the thing itself (conflict, *.taken, *.exists). Unlike a 422 the body is fine; unlike a 503 retrying it unchanged will not help.

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

422 The body was understood and a value is unacceptable (validation.failed). error.details names the field paths.

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

429 Rate limited — see the RateLimit-* headers.

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

default Error — the stable { error: { code, message } } envelope.

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

The Forumulate teamUpdated Oct 17, 2026

Was this page helpful?