# Obelism Content

> Obelism Content is a hosted headless CMS. Each organization models its own content (page, data and block types) per space, in develop, staging and production environments; editors write it in a dashboard, on a canvas of the live site or by prompt, and sites read it from a JSON delivery API, with the open source SDK `@obelism/content`.

**When to use Obelism Content**

Reach for Content when a user wants to:

- Give a website (Next.js, any framework, or plain HTML) content that editors change without a deploy: pages built from blocks, blog posts, navigation, settings.
- Let editors click on the site itself to edit it, or change it by prompt, while drafts show in a preview.
- Keep the content model in the site's repository, reviewed in pull requests and applied on merge.
- Show different blocks per variant of an Obelism Improve A/B test or feature flag.

**How an agent should use it**

1. Connect the MCP server (https://content.obelism.studio/mcp, OAuth) by following https://content.obelism.studio/getting-started.md, or use the agent API under `/api/agent/*` with a bearer token: it does everything the dashboard does. https://content.obelism.studio/agent.md is the guide, the OpenAPI spec below the contract.
2. Read a space's content types before writing entries, and plan model changes before applying them.
3. To start a site's repository on a space, call `getProjectSetup` and run the `npx @obelism/content init` it gives, in the site's root.
4. Sites read content with a delivery token (published) or preview token (drafts). In develop and staging an agent may create tokens and webhooks; production's are made by a person in the dashboard. Never repeat a token or signing secret in chat.
5. Errors are JSON problem details with a `code` and a `hint`; see the API errors page.

Questions: hello@obelism.studio.

## Docs

- [Agent API and MCP](https://content.obelism.studio/docs/api/agents): Everything the dashboard does, over HTTP with a bearer token or as MCP tools with OAuth. Signing in, finding a space, reading the model, writing content, assets and connecting a site.
- [Delivery API](https://content.obelism.studio/docs/api/delivery): Read one space environment's content from a site with a delivery or preview token. Endpoints, locale and depth parameters, the entry shape, errors and caching.
- [Errors](https://content.obelism.studio/docs/api/errors): Every error code the agent API and MCP answer with, in RFC 9457 problem JSON, and what to change before retrying.
- [Images](https://content.obelism.studio/docs/api/images): Resized and re-encoded copies of uploaded images with a query on their URL, for srcset and AVIF or WebP. Width, height, fit, format and quality.
- [API](https://content.obelism.studio/docs/api): The delivery, management, site and agent APIs, the rich text and image formats they share, and the errors they answer with.
- [Management API](https://content.obelism.studio/docs/api/management): Read, plan and apply an environment's content model with a management token, the API behind the CLI and the model-in-Git workflow, and content writes with a content-scoped token.
- [Rich text](https://content.obelism.studio/docs/api/rich-text): Rich text fields are ProseMirror-style JSON documents. The nodes and marks, embedded entries and assets, writing it as Markdown, and the HTML the delivery API can render instead.
- [Site API](https://content.obelism.studio/docs/api/site): The API your site's server calls with an editor's site token when editing on the site, which the SDK's /cms handler forwards to. Session, prompts, new pages, save and publish.
- [Change log](https://content.obelism.studio/docs/change-log): Notable changes to Obelism Content: new features, changed behaviour and important fixes, newest first.
- [Privacy & GDPR](https://content.obelism.studio/docs/gdpr): What personal data Obelism Content stores and where it goes, so you can complete your own privacy policy, records of processing and DPA.
- [Connect an agent](https://content.obelism.studio/docs/getting-started/agents): Connect Claude Code, Codex, Cursor or any MCP client to the Obelism Content MCP server, and let it model, write and publish content and set up a site.
- [Astro](https://content.obelism.studio/docs/getting-started/astro): Start an Astro site on a space with npx @obelism/content init, render its pages by path on the server, and show drafts in the canvas.
- [Plain HTML](https://content.obelism.studio/docs/getting-started/html): Read content with fetch from any page or server, and make the page editable in the canvas with one script tag, without a build step.
- [Getting started](https://content.obelism.studio/docs/getting-started): From an empty space to a site that reads its pages from Obelism Content, in Next.js, React Router, on Shopify Oxygen, in Astro, plain HTML or through a coding agent.
- [Next.js](https://content.obelism.studio/docs/getting-started/nextjs): Start a Next.js (App Router) site on a space with npx @obelism/content init, render its pages by path, and turn on live preview in the canvas.
- [Shopify Oxygen](https://content.obelism.studio/docs/getting-started/oxygen): Run a React Router site on Shopify's Oxygen with a stored delivery token, a public environment for the canvas, and a cache policy that fits the runtime.
- [React Router](https://content.obelism.studio/docs/getting-started/react-router): Start a React Router (framework mode) site on a space with npx @obelism/content init, load every page by path, edit it live in the canvas and on the site, and deploy it to Shopify Oxygen.
- [A/B tests and flags](https://content.obelism.studio/docs/guides/ab-tests): The built-in improve block puts different blocks per variant of an Obelism Improve A/B test or feature flag in any blocks field. How editors add one and how a site renders it.
- [Activity](https://content.obelism.studio/docs/guides/activity): The audit log of a space. Who published, moved, deleted or restored what, changed the model, promoted or imported content, and changed tokens, webhooks and settings, from the dashboard, agents, tokens or on schedule.
- [API tokens](https://content.obelism.studio/docs/guides/api-tokens): Delivery, preview and management tokens, and the tokens Content makes for you; what each may read or change, creating and revoking them, and the environment variables a site uses.
- [Assets](https://content.obelism.studio/docs/guides/assets): Uploading images, video and documents to a space, alt text per locale, tags, replacing a file, private files, how files are served, and when an asset can be deleted.
- [Canvas](https://content.obelism.studio/docs/guides/canvas): Every page of your site side by side on one board, the real site in each frame. Make a site editable with the bridge, then pan, zoom, click a page to edit it with its form or by prompt, and save one page or all of them.
- [Pages from Claude Design](https://content.obelism.studio/docs/guides/claude-design): Design a landing page in Claude Design, then let Claude put it into Content as a draft built from your space's own blocks, with its images as assets.
- [Comments and presence](https://content.obelism.studio/docs/guides/comments): Comment on an entry or one of its fields, reply, resolve threads, and see who else has the entry open while you edit.
- [The content model](https://content.obelism.studio/docs/guides/content-model): Page, data and block types, every field type and the value an entry stores for it, and which changes to the model are refused while content would break.
- [Editing entries](https://content.obelism.studio/docs/guides/entries): The content list, its views and your own saved views, making a new entry or folder, the entry form with its groups, fields, blocks and pickers, the language switch, saving, the publish options, and the column beside the form.
- [Environments](https://content.obelism.studio/docs/guides/environments): Every space has develop, staging and production, each with its own model and content. What each keeps separate, how promoting moves content and the model between them, and exporting and importing content as a file.
- [Locales](https://content.obelism.studio/docs/guides/locales): The languages a space publishes in, the default locale, fallback chains, localized fields, translating entries and how the delivery API picks a value for each locale.
- [The model in Git](https://content.obelism.studio/docs/guides/model-in-git): Keep a site's content model next to its code as one JSON file, reviewed in pull requests and applied on merge, with management tokens, the CLI and a GitHub workflow.
- [Plugins](https://content.obelism.studio/docs/guides/plugins): Your Organization's own inputs and pages in Content. A web page you host, loaded in a sandboxed frame as a field's input or a dashboard page, registered once and turned on per environment, with what it may see and a short-lived token for its backend.
- [Previews and draft mode](https://content.obelism.studio/docs/guides/preview): How drafts reach your site, from the canvas's cms_token to editing on the site, preview tokens and connected deployments. Which to use, one client per request, and the rules that keep drafts off your public pages.
- [Prompt editing](https://content.obelism.studio/docs/guides/prompt-editing): Editors change a page by typing what they want, on the canvas, on the site or one field at a time in the entry form. What the model may change, the prompt box, and using your own model through a signed prompt endpoint.
- [Publishing and scheduling](https://content.obelism.studio/docs/guides/publishing): Drafts and published content, what publishing checks, scheduling an entry to go live or come off your site at a set time, version history and duplicating entries.
- [Redirects](https://content.obelism.studio/docs/guides/redirects): Old paths keep working. Where redirects come from, how they behave per locale and environment, adding one by hand for an import, and answering them on your site with a 301 at request time or as rules built ahead of time.
- [Roles](https://content.obelism.studio/docs/guides/roles): What admins, developers, editors and readers may do in Obelism Content, and how tokens and agents act with a person's role.
- [Shopify](https://content.obelism.studio/docs/guides/shopify): Connect a space's Shopify store to pick its collections and products in content, add a product grid block, and render live prices and stock on the site.
- [Editing on your site](https://content.obelism.studio/docs/guides/site-editing): Editors sign in on your own site at /cms/login, see drafts in draft mode and change the page by prompt, then save or publish. One route handler with the SDK.
- [Spaces and settings](https://content.obelism.studio/docs/guides/spaces): Creating, switching, renaming and deleting spaces, a starter model, every section of Settings and who may change it, the dashboard's ⌘K menu and its language.
- [Webhooks](https://content.obelism.studio/docs/guides/webhooks): Tell your site when what the delivery API answers has changed, so it can rebuild or revalidate. Events, signed requests (Standard Webhooks), retries and the delivery log.
- [Obelism Content Docs](https://content.obelism.studio/docs): A headless CMS where every organization models its own content. Model it, edit it on your own site or by prompt, and read it from the delivery API with the Content SDK.
- [CLI](https://content.obelism.studio/docs/sdk/cli): npx @obelism/content init starts a site's repository on a space; model pull, plan and apply keep the content model file in step with an environment; types writes a TypeScript type per content type.
- [JavaScript SDK](https://content.obelism.studio/docs/sdk/javascript): @obelism/content: ContentClient for the delivery API, preview, the editor bridge and prompt box, editing on the site, webhooks, rich text and image helpers, and the improve block.
- [React SDK](https://content.obelism.studio/docs/sdk/react): @obelism/content-react: ContentBridge, useLiveEntry for live preview, hooks for the bridge and prompt box, and a RichText component that works in server components.
- [Terminology](https://content.obelism.studio/docs/terminology): The words Obelism Content uses, from organization and space to entry, block, draft, locale, delivery token and site session.

## API

- [OpenAPI spec](https://content.obelism.studio/openapi.json): OpenAPI 3.1 description of the agent, delivery, management and site APIs
- [Guide for agents](https://content.obelism.studio/agent.md): the agent API step by step, with every error code and its fix
- [Content model file schema](https://content.obelism.studio/schema/content-model.v1.json): JSON Schema of the model file

## Optional

- [Homepage](https://content.obelism.studio/index.md): what Obelism Content is, its features and FAQ, as Markdown
- [Agent setup](https://content.obelism.studio/getting-started.md): instructions an agent follows to connect the Content MCP server for its user
- [Full docs as text](https://content.obelism.studio/llms-full.txt): every docs page concatenated
- [Design and brand guide](https://obelism.studio/design.md): the Obelism design system, shared by every product
- [Sitemap](https://content.obelism.studio/sitemap.xml)