# Mojimoto > Mojimoto is a headless CMS. Content lives in **projects**; each project has > **content types** (schemas), **documents** (entries), and **locales** > (default `en-gb`). Everything is reachable over a JSON HTTP API, an MCP > server, and official SDKs. Human docs: https://mojimoto.com/docs ## Authentication All API and MCP requests use a project-scoped bearer token: Authorization: Bearer mjmt_<48 chars> Tokens are created in the mojimoto dashboard per project and carry abilities: - `read` - fetch published content (Delivery API) - `preview` - fetch draft content (`?ref=preview`; requires `read`) - `write` - create/update/publish documents and edit schemas (Write API, MCP) A token can also be **scoped**: limited to some operations (`draft`, `publish`, `delete`, `upload`, `model`) and/or some content types. Scopes apply to the Write API and MCP (a call outside them gets a `403` naming what the token may not do) and to delivery (out-of-scope types are hidden, `404`). Read tokens get read-only MCP (only the list tools). The project's **public** read token is refused by MCP. Error codes: `401` missing/invalid token · `403` token lacks ability or wrong project · `402` project subscription lapsed · `422` validation failed (body: `{"message", "errors": {"": ["..."]}}`) · `429` rate limited. Rate limits are per token, per minute (Starter plan defaults; higher plans raise them): delivery **300/min**, write **60/min**, MCP **120/min**. On `429` honour the `Retry-After` header, or back off exponentially. For bulk migrations, pace writes to ~1/second rather than blasting and retrying. Scripts should send a descriptive `User-Agent` (e.g. `my-migration/1.0`); edge bot protection may block default library UAs such as `Python-urllib`. ## Content modeling (read this before creating schemas) Every content type is a set of typed fields. Page sections go in a **`blocks` field** (an ordered list of typed sections stored inside the entry); content shared between entries is linked with **reference fields that point at other entries**. There are no nested groups. Every content type has a `format` that decides its cardinality and uid rules: - `page` - a **collection**: many entries, browsed as a list. Each entry **requires a unique `uid`** (its URL slug). The default format. - `single` - exactly **one** entry (navigation, site settings). Its uid is forced to `null`; creating a second entry is rejected. - `component` - a **building block edited inside its parent** (page sections, nav items). uid forced to `null`, hidden from the main content list, reachable only through the entry that references it. Note: the legacy `repeatable` boolean does **not** control this - setting `repeatable: false` alone does not make a single. Use `format`. ### The page → sections pattern (blocks) Model a page as a `page`-format type with a `blocks` field. `config.blocks` maps each block type api id to `{"label", "fields"}`; block fields may be `symbol`, `text`, `rich_text`, `number`, `boolean`, `date`, `select`, `media`, `location` or `json` (**no references inside blocks yet**). Do **not** serialise a page structure (e.g. a Prismic slice zone) into a `json` field - it gets no validation, no editor UI and no media handling. POST /api/v1/{project}/manage/content-types {"api_id": "page", "label": "Page", "format": "page"} POST /api/v1/{project}/manage/content-types/page/fields {"field": "sections", "definition": {"type": "blocks", "config": { "label": "Sections", "blocks": { "hero": {"label": "Hero", "fields": { "heading": {"type": "symbol", "config": {"label": "Heading", "required": true}}, "image": {"type": "media", "config": {"label": "Image"}}}}, "quote": {"label": "Quote", "fields": { "text": {"type": "text", "config": {"label": "Text"}}}}}}}} POST /api/v1/{project}/manage/documents {"type": "page", "uid": "home", "data": {"sections": [ {"type": "hero", "data": {"heading": "Welcome", "image": {"asset_id": 7, "fit": "cover"}}}, {"type": "quote", "data": {"text": "It just works."}}]}} Delivery returns each block as `{"id", "type", "data"}` in order (media expanded; use `id` as a render key). Publish errors name the block: key `sections.0.data.heading`, message `Sections, block 1 (Hero): Heading is required.` ### Shared sections with references When a section is reused across pages, make it an entry of a `component`-format type and link it with an ordered `references` field. End to end: # 1. The section type (a component - no uid, edited inside its parent) POST /api/v1/{project}/manage/content-types {"api_id": "hero_section", "label": "Hero", "format": "component"} POST /api/v1/{project}/manage/content-types/hero_section/fields {"field": "heading", "definition": {"type": "symbol", "config": {"label": "Heading"}}} POST /api/v1/{project}/manage/content-types/hero_section/fields {"field": "image", "definition": {"type": "media", "config": {"label": "Image"}}} # 2. The page type (a collection) with an ordered sections field POST /api/v1/{project}/manage/content-types {"api_id": "page", "label": "Page", "format": "page"} POST /api/v1/{project}/manage/content-types/page/fields {"field": "sections", "definition": {"type": "references", "config": {"label": "Sections", "content_types": ["hero_section"]}}} # 3. Content: create + publish a section, then the page referencing it POST /api/v1/{project}/manage/documents → {"id": 11, "uid": null} {"type": "hero_section"} POST /api/v1/{project}/manage/documents/11/publish {"data": {"heading": "Welcome", "image": {"asset_id": 7, "fit": "cover"}}} POST /api/v1/{project}/manage/documents → {"id": 12, "uid": "home"} {"type": "page", "uid": "home"} POST /api/v1/{project}/manage/documents/12/publish {"data": {"sections": [11]}} # 4. Delivery resolves the references in order GET /api/v1/{project}/documents?type=page&uid=home&depth=2 → {"results": [{"id": 12, "uid": "home", "type": "page", ..., "data": {"sections": [ {"id": 11, "uid": null, "type": "hero_section", ..., "data": {"heading": "Welcome", "image": {"id": 7, "url": "https://…/hero.jpg", "alt": "…", "width": 2400, "height": 1200, "content_type": "image/jpeg", "fit": "cover"}}} ]}}]} ## Field types `symbol` (short text), `text` (long text), `rich_text`, `number`, `boolean`, `date` (ISO 8601 date-time string), `select`, `media`, `reference`, `references`, `slug` (URL slug; max one per type - it syncs the document's `uid` on save), `location` (`{"lat", "lon"}`), `json` (arbitrary object - escape hatch only, see above). All api_ids and field ids must be **snake_case** (`^[a-z][a-z0-9_]*$`). Field definitions are `{"type": "...", "config": {...}}`. Config keys: - every type: `label`, `required` (enforced on publish), `description` (editor help text) - `symbol`/`text`: `min`, `max` (character length), `pattern` (regex), `placeholder` - `number`: `min`, `max` - `select`: `options` - an array of strings - `reference`/`references`: `content_types` - **required** allow-list of content type api_ids; every listed type must exist in the project - `blocks`: `blocks` - **required** map of block type api id → `{"label", "fields"}`; `min`, `max` (number of blocks) ### Write formats per field type What to put in `data` when writing a document: - `media` - `{"asset_id": , "fit": "cover"|"contain"}`. Upload the file first (see Assets) and use the returned id. **A raw image object (url + alt/dimensions but no `asset_id`) is rejected with a 422** - the metadata lives on the asset record. A bare URL string is accepted as a legacy value but delivers with `id`/`width`/`height`/`alt` all `null`; avoid it. - `reference` - a single entry id: `42` - `references` - an ordered array of entry ids: `[11, 12, 13]`. Order is preserved and is the render order. Ids are validated on publish: every entry must exist **in the same project**. - `rich_text` - an array of block nodes: `[{"type": "paragraph", "text": "Hello", "spans": []}]`. Block types: `paragraph`, `heading1`–`heading6`, `preformatted`, `list-item`, `o-list-item`, `image`, `embed`. Spans are `{"start", "end", "type"}` with type `strong`/`em`/`hyperlink` (hyperlink carries `"data": {"url": ...}`). Offsets are UTF-16 code units. An HTML string is also accepted and parsed into blocks - never stored as a string. - `blocks` - an ordered array of `{"type": "", "data": {...}}`; each block's `data` uses the same formats as top-level fields. Send an `id` (any string) to keep a block's render key stable across edits; if omitted, delivery derives one from the block's position and content. - `location` - `{"lat": 51.5, "lon": -0.1}` - `date` - ISO 8601 string · `boolean` - true/false · `number` - number · `symbol`/`text`/`select`/`slug` - string ## Delivery API (read) Base: `https://mojimoto.com/api/v1/{project}` {project} is the project's **ID** - the opaque handle shown in the dashboard (Settings → API keys) and in every URL the UI offers to copy. Legacy project slugs also resolve, so older slug-based URLs keep working; new integrations should use the ID. - `GET /documents` - list published documents. Query params: `type` (content type api_id), `uid`, `lang`, `page` (1-based), `per_page` (max 100), `sort` (`id|uid|created_at|updated_at`, `-` prefix for desc), `ref=preview` for drafts (needs `preview` ability - without it you get published content and an `X-Mojimoto-Preview: denied` header), `depth` (below). Returns `{"results": [...], "page", "per_page", "total_results", "total_pages", "lang", "ref"}`. - `GET /documents/{id}` - single document by id. Same `lang`/`ref`/`depth` params. 404 if the document has no published (or, with `ref=preview`, draft) version for the locale. - `GET /types` - the project's generated TypeScript types (a ready-to-save `.ts` module, served as `application/typescript`). Document shape: { "id": 42, "uid": "my-entry", "type": "gig", "lang": "en-gb", "status": "published", "published_at": "2026-06-12T14:30:45Z", "updated_at": "2026-06-12T14:30:45Z", "data": { "": , ... } } ### Reference resolution: `?depth=` `depth` controls how many levels of linked entries are inlined. Default `1`, clamped to `1`–`3`. At the edge of the budget a link collapses to a stub: {"id": 11, "type": "hero_section", "uid": null} For the page → sections pattern use `depth=2` when sections have references of their own (e.g. a section that references row cards); `depth=1` resolves the sections themselves. `media` fields resolve to full asset objects at any depth. A linked entry only inlines when it has a servable version: published content resolves published targets; `ref=preview` resolves the targets' drafts too. A target with no versions at all (created but never saved/published) always collapses to the stub - if a resolved reference comes back as a stub or with empty `data`, check the target was actually published, not just created. ## Write API (write ability) Base: `https://mojimoto.com/api/v1/{project}/manage` - `GET /content-types` - list schemas. Returns `{"content_types": [{"api_id", "label", "repeatable", "schema"}]}`; `schema` is `{"": {"": {"type", "config"}}}`. - `POST /content-types` - create: `{"api_id", "label"?, "format"?: "page"|"single"|"component", "icon"?}` → 201 `{"api_id", "schema"}`. Default format is `"page"`. Unknown parameters are rejected with a 422 (there is no `kind`/`singleton` - the cardinality lever is `format`). - `PUT /content-types/{type}` - update `label`/`format`/`icon` (fields are managed with the field endpoints). Format changes are guarded: to `"single"` only while the type has ≤1 entry; to `"page"` only when every entry has a uid. - `DELETE /content-types/{type}` - delete a type, allowed only while it has no documents (422 otherwise) - for recreating a type made with the wrong api_id or format. Deleting a type never deletes content. - `POST /content-types/{type}/fields` - add one field: `{"field": "", "definition": {"type", "config"}, "tab"?}` → 201. Fails if the field exists (field-level ops never clobber others). - `PUT /content-types/{type}/fields/{field}` - replace one definition - `DELETE /content-types/{type}/fields/{field}` - remove one field - `GET /documents` - list documents in all statuses, `?type=`/`?uid=`/`?lang=`. Returns `{"results": [{"id", "uid", "type", "has_published", "data"}]}` where `data` is the current **draft** content. Not paginated. **There is no `GET /manage/documents/{id}`** - read a document back through the Delivery API (`GET /documents/{id}?ref=preview` for drafts). - `POST /documents` - create: `{"type": "", "uid"?, "lang"?, "data"?}` → 201 `{"id", "uid", "version_id"?}`. `uid` is required for `page`-format (collection) types and must be omitted/null for `single`/`component` types. Passing `data` saves it as the initial draft (same field formats as PUT); publishing is still a separate call. A document created without `data` has **no versions yet**: it 404s on delivery (even with `ref=preview`) and any reference to it resolves as a bare `{id, type, uid}` stub until content is saved and published. - `PUT /documents/{id}` - save a draft: `{"lang"?, "data": {...}}` → `{"version_id", "status"}`. Field rules are NOT enforced here (drafts may be incomplete), but value shapes are normalised and bad media values are rejected. - `POST /documents/{id}/publish` - publish: `{"lang"?, "data"?}` (omit `data` to publish the latest draft) → the serialized document, as delivery returns it. Validates required fields, reference/media project scoping, and min/max/pattern - 422 with per-field `errors` on failure. - `POST /documents/{id}/unpublish` - take a locale off the delivery API: `{"lang"?}`. The published content is kept as the working draft, delivery 404s, and references to the entry collapse to stubs. Publish again to restore. 422 when the locale is not published. - `DELETE /documents/{id}` - permanently delete a document and its history. References that pointed at it resolve to null (single) or drop out of the list (many). Prefer unpublish when the content might come back. - `POST /assets` - upload a file (see Assets) All writes are audit-logged and attributed to the token name. ## Assets (media uploads) Upload before writing any `media` field: POST /api/v1/{project}/manage/assets Content-Type: multipart/form-data file: (binary, max 20MB) alt: optional alt text, delivered with every use of the asset filename: optional override → 201 {"id": 7, "url": "https://…/hero.jpg", "filename": "hero.jpg", "mime_type": "image/jpeg", "width": 2400, "height": 1200, "alt": "A hero image"} Then write the media field as `{"asset_id": 7, "fit": "cover"}`. Delivery expands it to the full object (`id`, `url`, `alt`, `width`, `height`, `content_type`, `fit`). Over MCP, use `upload-asset-tool` instead (it accepts a public URL or base64 content). ## MCP server Streamable-HTTP MCP endpoint per project (a `write` token gets the tools its scopes allow; a `read` token gets the read tools only): https://mojimoto.com/mcp/{project} Add to Claude Code: claude mcp add --transport http mojimoto https://mojimoto.com/mcp/{project} \ --header "Authorization: Bearer mjmt_..." Or set up Claude Code, Cursor and Codex in one go (writes a Mojimoto skill with the project's content model, CLAUDE.md/AGENTS.md notes, Cursor rules, and the MCP server in `.mcp.json`/`.cursor/mcp.json` reading `MOJIMOTO_WRITE_TOKEN` from the environment): npx @mojimoto/cli init --project {project} --token mjmt_ Resource: `mojimoto://content-model` - every content type and its fields. Tools: list-content-types-tool, list-documents-tool, create-document-tool, update-document-tool, publish-document-tool, unpublish-document-tool, delete-document-tool, upload-asset-tool, create-content-type-tool, update-content-type-tool, add-field-tool, update-field-tool, remove-field-tool. ## SDKs (npm) - `@mojimoto/client` - core JS/TS client - `@mojimoto/next` - Next.js wrapper (Data Cache, revalidateTag, Draft Mode) - `@mojimoto/react`, `@mojimoto/vue`, `@mojimoto/nuxt`, `@mojimoto/richtext` TypeScript types for a project's schema are generated by the API itself: npx @mojimoto/cli types --endpoint https://mojimoto.com/api/v1 \ --project --token $MOJIMOTO_TOKEN # or plain HTTP: curl -H "Authorization: Bearer $MOJIMOTO_TOKEN" \ https://mojimoto.com/api/v1//types -o mojimoto.generated.ts Quick start (Next.js): import { createMojimotoClient } from "@mojimoto/next"; export const cms = createMojimotoClient({ endpoint: "https://mojimoto.com/api/v1", project: "", token: process.env.MOJIMOTO_TOKEN!, revalidate: 60, tags: ["cms"], }); const gigs = await cms.all({ type: "gig", sort: "-updated_at" }); const home = await cms.byUid("page", "home", { depth: 2 }); // sections inlined Core client (`@mojimoto/client`) exposes the same `createClient` options plus `query`, `all`, `first`, `byUid`, `byId` - every method accepts `depth?: 1 | 2 | 3`. Nuxt (`@mojimoto/nuxt` - SSR composables, auto-imported): const { data: page } = await useMojiDocument("page", "home", { depth: 2 }); const { data: posts } = await useMojiQuery({ type: "blog_post", perPage: 12 }); ## Migrating from Prismic - **Slice zone → `blocks` field.** Each slice type becomes a block type in the field's `config.blocks`; write each slice as `{"type", "data"}` in order. A slice with a link to another document can't live in a block yet: make that slice a `component`-format type in a `references` field instead. Do not park the slice-zone JSON in a `json` field. - **Rich text is intentionally block-compatible.** Prismic StructuredText blocks can be written as-is - same `{type, text, spans}` model. Drop each block's `direction` and any span `key`s before writing (they are stored and echoed back, but nothing reads them). `embed` blocks, `label` spans and document-link spans survive delivery but have no editor UI yet: their text survives an editor round-trip, the decoration does not. - **Images: upload, then link.** For each Prismic image, download its `url` (or pass the URL to the MCP `upload-asset-tool`), POST it to `/manage/assets` with the Prismic `alt`, and write `{"asset_id": , "fit": "cover"}`. Writing the Prismic image object itself is rejected. - **Links.** Web links → a `symbol` field holding the URL. `Link` fields with `select: "document"` → a `reference` field; write the target entry's id. - **UID field → `slug` field** (and pass the value as `uid` when creating each document). Prismic `GeoPoint` → `location` (`latitude/longitude` → `lat/lon`). `Timestamp`/`Date` → `date`. `Select` → `select` with `options`. `Number`/`Range` → `number`. `Color` → `symbol`. - Locale codes are lowercase (`en-gb`, not `en-GB`). ## Optional - Human documentation: https://mojimoto.com/docs - Webhooks and preview environments: see /docs sections "Webhooks" and "Preview"