How to Build a Headless CMS with Fastio API

Content management has moved past monolithic systems. Building a headless CMS with the Fastio API lets developers use scalable workspaces and file metadata to serve structured content to any frontend framework.

In a traditional CMS, your content backend and presentation layer are tightly coupled. Displaying content across a website, mobile app, and digital billboard often requires different systems or workarounds. Headless architectures offer more flexibility. By separating where content lives from where it appears, you can build a central repository and serve that data anywhere via APIs.

Fastio reduces the need for managing separate database backends for digital assets. Instead of maintaining a relational database to track image locations and blog posts, you store articles as notes, media as files, and organize both in workspace folders. Notes hold the markdown body. Files hold images and video. Your application layer holds the schema for properties like publish dates and author names.

This approach is framework-agnostic. Whether you build an e-commerce site with Next.js, a corporate blog with Astro, or a mobile app in React Native, the API returns standard JSON. Frontend developers can focus on the user experience instead of database migrations or ORM configurations, giving you the freedom to choose the right rendering technology for the job.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

While many headless CMS options exist, Fastio operates as an intelligent workspace rather than basic commodity storage. It works as a coordination layer where agent output becomes team output.

When you use Fastio as your CMS backend, intelligence is built in. Toggling Intelligence Mode auto-indexes files the moment they are uploaded. You bypass the need for a separate vector database or search indexing pipelines. Content becomes searchable by meaning, and you can ask natural language questions about your repository using Ripley, the built-in RAG agent.

The Business Trial offers persistent storage, high maximum file size limits, and a monthly credit allowance. Agents connect over MCP at https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with a Bearer header). Named mode exposes 19 tools, including storage, upload, workspace (notes), ai, find, and event. Code mode for headless agents exposes 6 tools: auth, upload, search, execute, room, and how-to.

To rebuild a static site when editors publish, long-poll workspace activity with GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}, or read the audit log at GET /current/events/search/. Import a remote asset with POST /current/web_upload/ (source_url, file_name, profile_id, profile_type set to workspace or share, and folder_id) so media never has to pass through your laptop. Fastio gives you a multi-agent workspace that is ready for modern frontends.

The first step in building your headless CMS is configuring your Fastio organization and workspace. A workspace acts as an isolated container for your files, notes, metadata, and intelligence settings.

Start by creating a developer organization. Inside it, generate a new workspace dedicated to your CMS content, such as production-cms-content. Workspace IDs are 19-digit numeric strings. After creating the workspace, generate an API key in Settings > Devices & Agents > API Keys, or with POST /current/user/auth/key/. Authenticated calls use Authorization: Bearer {api_key} against https://api.fast.io/current/. Keep the trailing slashes.

A useful platform feature is ownership transfer. An AI agent or freelance developer can create an organization, build the CMS workspace structure, add initial content, and then transfer ownership to the primary team. The original creator can retain admin access if needed to help with the handoff.

Organizing your workspace logically is important. A common pattern involves creating top-level directories for different content types. You might use a /posts folder for published articles, a /drafts folder for work in progress, an /authors folder for author bios, and a /media folder for images. Create those folders with POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/. Because the platform supports hierarchical folders, this structure maps directly to URL routing on your frontend.

Here is an example API call using standard command-line tools to verify your connection and list the root directory contents. Pass your API key as a Bearer token in the Authorization header:

curl -X GET "https://api.fast.io/current/workspace/YOUR_WORKSPACE_ID/storage/root/list/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Once this request returns a successful JSON response, your workspace is ready to accept content and act as your backend.

In a database-driven CMS, you spend time writing migrations to add new columns. In Fastio, you define your content metadata schema in the application layer and keep article bodies as notes. You enforce the schema in your publish scripts and frontend before you write.

When you create a markdown blog note, your app validates a metadata object that describes it. This metadata acts like the columns in a traditional database table.

For a blog article, a metadata schema might look like this:

{
  "type": "article",
  "title": "Introduction to Next.js API Routes",
  "slug": "intro-to-nextjs-api-routes",
  "authorId": "user_abc",
  "published": true,
  "publishDate": "2026-03-01T10:00:00Z",
  "tags": ["javascript", "react", "backend"],
  "seo": {
    "description": "A comprehensive guide to building APIs with Next.js.",
    "ogImage": "/media/headers/nextjs-intro.png"
  }
}

By applying this schema to every article in the /posts directory, you create a consistent dataset. The type field is important because it lets your application differentiate between articles, product listings, and author profiles during data fetching.

To maintain consistency, validate this metadata schema before you create the note. Use validation libraries in your backend API routes or publish scripts to ensure required fields are present and formatted correctly. This prevents broken frontend pages caused by missing data.

When you want structured fields pulled from existing documents, create a metadata template with POST /current/workspace/{workspace_id}/metadata/templates/ and extract with POST /current/workspace/{workspace_id}/storage/{node_id}/metadata/extract/.

Give Your AI Agents Persistent Storage

Get started with Fastio's developer tier to build scalable headless architectures with native intelligence. Built for how build headless cms with fast api workflows.

Start 14-Day Trial

With your workspace configured and your metadata schema defined, the next step is publishing content. Markdown articles belong in notes. Media files belong in the upload API. Notes and files are not interchangeable, even when the article is markdown.

Create a new article with POST /current/workspace/{workspace_id}/storage/{parent_id}/createnote/ under your posts folder. Read it back with GET /current/workspace/{workspace_id}/storage/{node_id}/readnote/. Update it later with POST /current/workspace/{workspace_id}/storage/{node_id}/updatenote/. Use root or the posts folder node ID as {parent_id}.

Upload images and other binaries with a multipart POST to https://api.fast.io/current/upload/. Send name, size, chunk (the bytes), action=create, instance_id (the workspace ID), and folder_id (use the media folder node ID, or root). A successful small upload returns HTTP 201 with {"result":true,"id":"<upload_id>","new_file_id":"<node_id>"}. Same-name upload into the same folder overwrites in place and keeps the old content as a recoverable version. The node_id stays stable.

Here is a script using the native fetch API to upload a media file into the CMS workspace:

async function uploadMedia(fileName, fileBytes, fileSize) {
  const formData = new FormData();
  formData.append('name', fileName);
  formData.append('size', String(fileSize));
  formData.append('chunk', new Blob([fileBytes]), fileName);
  formData.append('action', 'create');
  formData.append('instance_id', process.env.FASTIO_WORKSPACE_ID);
  formData.append('folder_id', process.env.FASTIO_MEDIA_FOLDER_ID);

const response = await fetch('https://api.fast.io/current/upload/', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.FASTIO_API_KEY}`
    },
    body: formData
  });

if (!response.ok) {
    throw new Error('Failed to upload content');
  }

return await response.json();
}

If you use AI agents to generate content, connect them to MCP at https://mcp.fast.io/mcp. Named mode includes workspace actions create-note, read-note, and update-note, plus upload for media. A typical tools/call looks like this:

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"upload","arguments":{"action":"web-import","url":"https://example.com/report.pdf",
 "profile_type":"workspace","profile_id":"1234567890123456789"}}}

When running concurrent multi-agent systems, Fastio file locks prevent conflicts. Agents acquire a lock with POST /current/workspace/{workspace_id}/storage/{node_id}/lock/ before updating, and release it with DELETE on the same path, so multiple agents do not overwrite each other's changes while editing the same post.

The final step is consuming the content. Your frontend application lists the posts folder and reads each note from Fastio to render the pages. Because the API returns standard JSON, this process works well with modern frontend frameworks.

To render a blog index page, list the /posts folder with GET /current/workspace/{workspace_id}/storage/{parent_id}/list/. Query params sort_by (name, updated, created, or type), sort_dir (asc or desc), page_size (100, 250, or 500), and cursor page through the folder. Follow pagination.has_more and pagination.next_cursor rather than assuming a short page is the end.

Keep drafts in a separate folder so the public index only lists published notes. Create those folders with POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/.

Once you have the note list, rendering the index page is straightforward. When a user opens a post, your application reads that note with GET /current/workspace/{workspace_id}/storage/{node_id}/readnote/. Parse the markdown with a standard library to render HTML.

Here is an example of listing the posts folder inside a server component:

export async function fetchPublishedPosts() {
  const workspaceId = process.env.FASTIO_WORKSPACE_ID;
  const postsFolderId = process.env.FASTIO_POSTS_FOLDER_ID;
  const response = await fetch(
    `https://api.fast.io/current/workspace/${workspaceId}/storage/${postsFolderId}/list/?sort_by=updated&sort_dir=desc&page_size=100`,
    {
      headers: {
        Authorization: `Bearer ${process.env.FASTIO_API_KEY}`
      }
    }
  );

if (!response.ok) {
    throw new Error('Failed to list posts');
  }

return await response.json();
}

This retrieval process shows the practical value of headless architectures. The frontend requests exactly the folder it needs, then reads individual notes as the reader opens them.

A headless CMS must also handle media files. Images, videos, and downloadable documents are standard parts of web projects. Upload these as files, not notes, into a dedicated /media directory in your workspace.

When an author drafts a blog post with inline images or a hero header, upload those images to the media folder. The platform supports high-resolution photography and video files without the strict size limits of older systems.

After uploading an image, read the bytes with GET /current/workspace/{workspace_id}/storage/{node_id}/read/, or request a preview with GET /current/workspace/{workspace_id}/storage/{node_id}/preview/{preview_type}/read/. Valid preview_type values include thumbnail, image, mp4, hlsstream, audio, and pdf. Your application maps those node IDs into img and video tags. The application server does not need to store the binaries itself.

You can also run metadata extraction on media files with POST /current/workspace/{workspace_id}/storage/{node_id}/metadata/extract/. Storing extracted details with the asset helps frontend developers meet accessibility standards without duplicating files.

For remote assets, import from a URL with POST /current/web_upload/ (source_url, file_name, profile_id, profile_type set to workspace or share, and folder_id). Agents can do the same with the MCP upload tool and action web-import.

When moving your headless CMS to production, several practices help maintain performance and security.

First, cache your API responses. Making a network request for every page view slows down your site. If you use a modern rendering framework, use Static Site Generation or Incremental Static Regeneration to build your pages at compile time. The content gets baked into the HTML, which improves load times.

To keep cached content fresh, long-poll GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp} or read GET /current/events/search/. When the posts folder changes, trigger a background rebuild of your static site. Editors update a note, and the live site reflects the changes without a manual deploy.

Next, separate your environments. Avoid using the same workspace for staging and production. Create a dedicated staging workspace to test changes and preview drafts. Once validated, copy those notes and files to the production workspace with POST /current/workspace/{workspace_id}/storage/{node_id}/copy/. This isolation prevents accidental publications.

Finally, write clear error handling. Network requests fail, and a note might be missing a heading due to human error during publish. Your frontend data fetching logic should include retries. HTTP 429 with error code 1671 means you should back off until the x-ve-limit-expires header. Provide fallback values and default images in your code so the application doesn't crash over a single malformed note. These guidelines keep your CMS reliable.