Base URL & Versioning

Configure your API base URL, understand versioning strategies, and ensure your integration stays stable as FlowCMS evolves.

Overview #

FlowCMS exposes a RESTful API and a GraphQL endpoint that allow you to programmatically create, read, update, and delete content. Every API request is made against a base URL that includes your project identifier and the API version.

Understanding how to configure and use base URLs — along with FlowCMS's versioning strategy — is essential for building resilient integrations that won't break when we release new features.

Base URL Structure #

The FlowCMS API base URL follows a consistent structure across all environments:

https://{project-id}.api.flowcms.io/{api-version}/{resource}

URL Components

Examples

# List all entries
https://acme-corp.api.flowcms.io/v3/entries

# Get a specific entry
https://acme-corp.api.flowcms.io/v3/entries/blog-post-slug

# Upload an asset
https://acme-corp.api.flowcms.io/v3/assets/upload

# GraphQL endpoint
https://acme-corp.api.flowcms.io/v3/graphql

Configuring Your Base URL #

You can set your base URL in several ways depending on your integration approach. Here's how to configure it across different environments.

Environment Variables

The recommended approach is to store your base URL in environment variables:

FLOWCMS_BASE_URL=https://your-project.api.flowcms.io/v3
FLOWCMS_ACCESS_TOKEN=fcm_live_sk_abc123...
FLOWCMS_PREVIEW_TOKEN=fcm_preview_pk_xyz789...

SDK Configuration

FlowCMS provides official SDKs for popular languages. Each SDK handles the base URL automatically:

import { FlowCMS } from '@flowcms/js-sdk';

// Initialize with project ID and token
const flow = new FlowCMS({
  projectId: 'acme-corp',
  accessToken: process.env.FLOWCMS_ACCESS_TOKEN,
  apiVersion: 'v3',
  baseUrl: 'https://acme-corp.api.flowcms.io' // optional override
});

// Fetch entries
const entries = await flow.entries.getAll({
  type: 'blog_post',
  limit: 10
});

from flowcms import Client

# Initialize with project ID and token
flow = Client(
    project_id="acme-corp",
    access_token=os.getenv("FLOWCMS_ACCESS_TOKEN"),
    api_version="v3",
    base_url="https://acme-corp.api.flowcms.io"  # optional override
)

# Fetch entries
entries = flow.entries.get_all(
    type="blog_post",
    limit=10
)

use FlowCMS\Client;

// Initialize with project ID and token
$flow = new Client([
    'project_id'  => 'acme-corp',
    'access_token' => $_ENV['FLOWCMS_ACCESS_TOKEN'],
    'api_version' => 'v3',
    'base_url'     => 'https://acme-corp.api.flowcms.io',
]);

// Fetch entries
$entries = $flow->entries->getAll([
    'type'  => 'blog_post',
    'limit' => 10,
]);

import (
    "github.com/flowcms/go-sdk"
    "os"
)

// Initialize with project ID and token
flow := flowcms.NewClient(flowcms.Config{
    ProjectID:   "acme-corp",
    AccessToken: os.Getenv("FLOWCMS_ACCESS_TOKEN"),
    APIVersion:  "v3",
    BaseURL:     "https://acme-corp.api.flowcms.io",
})

// Fetch entries
entries, err := flow.Entries.GetAll(
    flowcms.EntryFilter{
        Type:  "blog_post",
        Limit: 10,
    },
)

API Versioning Strategy #

FlowCMS uses URL-based versioning to ensure backward compatibility. Each major version of the API is isolated, allowing you to upgrade at your own pace. We never introduce breaking changes to an existing version. Once a new major version is stable, the previous version enters a deprecation window.

Current API Versions

Version Specifiers

You can pin your integration to a specific version or use a range specifier to automatically receive patch-level updates:

# Pin to exact version (recommended for production)
v3

# Allow patch updates within major version
v3.*

# Specific minor and patch version
v3.2.1

# Latest stable version (not recommended for production)
v3.latest

Version via Header

Alternatively, you can specify the API version using the X-FlowCMS-Version request header. This is useful when you want to test multiple versions without changing your base URL.

curl https://acme-corp.api.flowcms.io/entries \n    -H "X-FlowCMS-Version: v3.2.1" \n    -H "Authorization: Bearer fcm_live_sk_abc123..." \n    -H "Content-Type: application/json"

Core API Endpoints #

All endpoints are relative to your base URL. Here are the most commonly used endpoints with v3:

GET /v3/entries?type=blog_post&limit=10&offset=0&fields=title,slug,date

{
  "data": [
    {
      "id": "ent_abc123",
      "title": "Getting Started with FlowCMS",
      "slug": "getting-started-with-flowcms",
      "date": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 142,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

GET /v3/entries/getting-started-with-flowcms

{
  "type": "blog_post",
  "fields": {
    "title": "My New Post",
    "slug": "my-new-post",
    "body": "<p>Content here...</p>",
    "status": "draft"
  }
}

query GetBlogPosts {
  entries(type: "blog_post", limit: 10) {
    data {
      id
      title
      slug
      date
      author {
        name
        avatar
      }
    }
    meta {
      total
    }
  }
}

Migrating Between Versions #

When upgrading between API versions, review the changelog for breaking changes and follow our migration checklist:

1. Review the changelog — Identify all breaking changes between your current version and the target version.
2. Update your SDK — Ensure your SDK version is compatible with the target API version.
3. Test in staging — Deploy your changes to a staging environment first and run integration tests.
4. Update your base URL — Change the version in your base URL from v2 to v3.
5. Monitor error rates — After deployment, watch for any increase in 4xx/5xx errors in your monitoring dashboard.

Notable Breaking Changes in v3

Frequently Asked Questions #

Can I use multiple API versions in the same project?

Yes. Different parts of your application can use different API versions. This is useful when you're gradually migrating a large codebase. Just make sure each API call includes the correct version in its URL or header.

What happens when a version reaches end of life?

When an API version reaches its end of life date, it will return 410 Gone responses with a migration guide URL in the response body. We recommend upgrading before this date to avoid service disruption.

Can I host FlowCMS with a custom domain?

Yes. Self-hosted and Enterprise plans support custom domains. In this case, your base URL would be something like https://cms.yourcompany.com/v3 instead of the FlowCMS cloud domain. Contact our sales team for details.

How do I find my project ID?

Navigate to Settings → Project in the FlowCMS dashboard. Your project ID is displayed at the top of the page. It's a unique, lowercase, hyphenated identifier (e.g., acme-corp).