FAQs

Content and delivery

What does Cli Blog store for a post body?

Cli Blog stores plain Markdown in body_markdown. Your application chooses the Markdown renderer and presentation. Sanitize rendered HTML according to your framework and security policy.

Can I store MDX components in a post?

Cli Blog does not promise an MDX execution environment. Store portable Markdown in body_markdown. If your product supports a controlled extension syntax, parse and map it in your own rendering layer instead of executing arbitrary components from content.

Can I use Cli Blog without the Node SDK?

Yes. The REST API works with any technology that can send HTTP requests. The Node SDK, CLI, dashboard, and agent skill are different interfaces over the same resources.

See Tools to choose by environment and task.

Can a browser read posts directly?

Yes. Use a public key to read published delivery content. Public keys cannot create, update, publish, schedule, or delete content.

const response = await fetch(
  "https://api.cli-blog.com/v1/posts?status=published&fields=summary",
  { headers: { "x-api-key": PUBLIC_CLI_BLOG_KEY } },
);

If the browser reports a CORS failure, confirm the request goes directly to the production API origin, uses an allowed method and header, and is not being redirected. A server-side request is a reliable fallback while the origin configuration is corrected.

Should I use the Node SDK in a browser?

No. @cli-blog/node targets Node.js 20+ and trusted environments. Browser delivery should use fetch with a public key. Keep private SDK operations behind an authenticated server route.

How should I cache published content?

Cache successful published reads at the server, CDN, framework data layer, or static build according to how quickly the site must reflect changes. Do not cache private write responses, authentication errors, rate-limit responses, or temporary service failures as valid content.

Revalidate the post list, affected slug, sitemap, and feed after a publishing workflow succeeds.

API keys and security

Which key should I use?

Use a public key for published-content delivery. Use a private key only in trusted servers, CI jobs, local shells, CLIs, and agent environments that need editorial access.

See API keys for permissions, storage, rotation, naming, and incident response.

Can I expose a public key?

Public keys are designed for delivery clients, including browsers. They are read-only and organization-scoped. Keep them managed and separate by environment so you can identify traffic and rotate a key when needed.

Can I expose a private key?

No. Never place a private key in browser or mobile bundles, public environment variables, prompts, screenshots, logs, generated docs, public repositories, or customer-visible errors.

Why does a valid key receive 403?

A 403 means the key is recognized but its type or permissions do not allow the action. Common cases are using a public key for editorial fields, using a private key without the resource action, or attempting publication without post publish permission.

Does a private API key authenticate my users?

No. Authenticate and authorize users in your own application before a server route performs a private Cli Blog request. Add session checks, role checks, CSRF protection where applicable, schema validation, input limits, and local rate limiting.

Slugs, locales, and translations

How are slugs scoped?

Post slugs are unique within an organization, content type, and locale. Category and tag slugs are likewise locale-scoped within their resource type. Always send locale when the same slug could exist in more than one language.

Can a post slug change?

Yes. When a post's slug changes, use the slug-redirect resource to resolve the earlier slug. Your delivery application can redirect the old route to the current one.

See Revisions and redirects.

Do locales fall back automatically?

No. Cli Blog does not silently substitute another locale. Request the locale that contains the content you want and define any fallback behavior in your application.

Which locales are available?

Call the keyless locale endpoint:

curl "https://api.cli-blog.com/v1/locales"

Or run cli-blog locales list --json. Locale values are curated BCP 47 tags such as en-US, es-MX, and es-ES.

How do translations relate to the source post?

Each translation is a normal post row with its own locale, title, slug, Markdown, and SEO fields. Create it with translation_of_id pointing to an existing post. The API links the translation group and can inherit authors, category and tag assignments, and shared media unless the request overrides them.

Translate and review each locale explicitly. Linking posts does not translate their text.

Fields, includes, and pagination

What is the difference between fields and include?

fields chooses groups of post fields. include embeds related resource objects.

Request only what the page needs. A listing commonly uses fields=summary,seo&include=authors,media; a post page adds content, categories, and tags.

Why does a post response omit a field?

The delivery response stays lean by default. Add the field group that contains the missing value. For example, request fields=content for body_markdown and generated table_of_contents, or fields=seo for search and social metadata.

Why does a response contain IDs but not related objects?

IDs preserve relationships without expanding every object. Add the corresponding include, such as include=authors,categories,tags,media, when the page needs embedded details.

Why is the list limit capped at 100?

The cap bounds response size, database work, serialization, and client memory. It is a per-request safety boundary, not a content limit. Follow next_cursor or use the Node SDK paginate() iterator to retrieve more than 100 results.

Should I use cursors or numbered pages?

Use cursors for load-more interfaces, synchronization, exports, audits, and long traversals. They are the recommended, more efficient mode. Use numbered pagination only when the interface needs exact totals or page jumps; counting the entire filtered result set adds work.

See Pagination for complete REST and SDK loops.

Authors, categories, tags, and media

Are dashboard members and public authors the same thing?

No. Members are people with organization access. Authors are public byline profiles returned with published content. An author may be connected to a member, but create and assign an author profile before using it in author_profile_ids.

What is the difference between categories and tags?

Categories provide structured navigation and can have up to two child levels below a root category. Tags are flat, flexible topics. Both support localized names, slugs, descriptions, and SEO fields.

How do I upload media?

Send POST /v1/media as multipart/form-data with a private key and the file in the file field. The API stores the file and returns its ID, delivery URL, MIME type, dimensions, byte size, and editorial metadata.

See Media for REST, Node SDK, and CLI examples.

Can I register an image by remote URL?

No. Media creation is upload-first. Upload the file so Cli Blog can generate the storage URL and metadata consistently. Media metadata updates remain JSON requests.

Can I resize or convert an uploaded image?

Yes. Keep the original media ID and request delivery variants through the image URL parameters documented in the media guide. Use the size, crop, quality, and modern format appropriate for each layout while preserving the uploaded source.

Does removing an attachment delete the media asset?

No. Post attachments are links to media assets. Removing an ID from media_asset_ids unlinks it from the post; it does not delete the underlying asset.

Workflow, revisions, and automation

Does creating a post publish it?

Not unless you set status: "published". Omitted status defaults to draft. The canonical workflow is the post status field; SDK publish() and schedule() methods are shortcuts for common status updates.

Can I schedule a post?

Yes. Set status: "scheduled" and an ISO 8601 scheduled_at in the same request, or use the Node SDK schedule() helper. A scheduled time at or before now is accepted and publishes on the next scheduler run.

What are revisions?

Revisions are read-only snapshots of earlier post versions. Use a private key with post read permission to list or retrieve them. There is no one-call restore method; retrieve the chosen revision, review its content, and send an intentional post update with the current expected_version.

What happens when I delete a post?

The delete action removes the post from normal delivery. Treat it as a destructive action and require confirmation. For a temporary editorial removal, choose the workflow state that matches your process rather than automating deletion.

Does Cli Blog send content webhooks?

Cli Blog does not currently expose customer-facing content webhooks. A publishing service already knows when its own create or update request succeeds and can trigger local revalidation then. For changes made elsewhere, use bounded polling with cursor lists or a scheduled synchronization job.

Do not build against internal billing or dashboard callbacks; they are not content integration endpoints.

Can an agent create a draft without publishing it?

Yes. Give the agent a scoped private key, require status: "draft", and ask it to return the post ID, slug, locale, version, relationships, checks, and review notes. Publish or schedule only after approval of that exact version.

What does the agent skill add?

The skill gives supported agents durable Cli Blog context: tool selection, key safety, draft-first behavior, approval gates, and links to API, SDK, CLI, and framework references. It does not bypass permissions or run without the tools and credentials you provide.

See Build with AI for a complete inspect, draft, review, publish, and verify workflow.

Errors and reliability

How should I handle API errors?

Log the method, path, status, safe error code, and request ID. Never log API keys or complete request headers.

Which requests are safe to retry?

Retry transient reads after 429, 502, 503, or 504 with bounded exponential backoff and jitter. Do not automatically repeat writes unless your workflow can prove the operation is safe to repeat. A timeout after a write can mean the server completed the change even though the client missed the response.

How do I avoid overwriting another editor?

Send expected_version when updating, publishing, or scheduling a reviewed post. A stale version returns 409; fetch the current post, reconcile the changes, and ask for approval again if the public result changed.

Sitemap and feed

How do I add a sitemap to my website?

Proxy GET /v1/sitemap or /v1/sitemap.xml onto /sitemap.xml on your own domain. The response contains published, indexable post URLs. Pass locale when you need one language; omit it to include every published, indexable localized URL.

How do I add an RSS feed?

Proxy GET /v1/feed or /v1/feed.xml onto /feed.xml on your own domain. The RSS feed uses one locale and returns published, indexable posts up to the requested limit.

Why is my sitemap or feed missing a post?

Confirm the post is published, indexable, in the requested locale, and associated with the expected organization publication settings. A scheduled, draft, archived, or noindex post does not belong in public discovery output.

Teams and billing

Can editors and developers share an organization?

Yes. Roles include owner, admin, developer, editor, publisher, and member. Roles control access to settings, members, keys, content actions, media, categories, tags, and publication.

Does every invited member need a subscription?

No. Billing belongs to the organization. Invited members use that organization's subscription and do not buy a separate plan.

What are the plan limits?

Check the pricing page for current prices and plan packaging.

What happens when usage approaches a limit?

Owners and admins receive notices at 80%, 95%, and 100%. Trusted API requests, storage, locales, and members have a 10% grace window before additional usage is blocked. Public delivery reads are monitored separately during paid beta and do not consume trusted request capacity. Media-delivery usage is monitored separately. Starter and Pro organizations can upgrade, and Business customers can contact the team about Enterprise requirements.

Can one subscription cover multiple organizations?

No. Content, keys, members, settings, and billing are organization-scoped. Each organization needs its own active subscription or card-backed trial.