Go SDK

The ButterCMS Go SDK provides an idiomatic Go interface for pages, collections, blog posts, and feeds — ideal for Go web apps, APIs, and microservices.

Installation

Install the SDK using Go modules:

go get github.com/buttercms/buttercms-go

The SDK uses Go modules for dependency management, ensuring version compatibility and reproducible builds.

Initialization

Configure the SDK with your Read API token from the ButterCMS Settings.

package main

import (
    "github.com/buttercms/buttercms-go"
)

func main() {
    ButterCMS.SetAuthToken("your_api_token")
}

Configuration options

ButterCMS.SetAuthToken("your_api_token")  // Set your Read API token
ButterCMS.SetPreviewMode(true)            // Enable preview mode for draft content

Function	Description
SetAuthToken(token string)	Set your ButterCMS Read API token (required)
SetPreviewMode(enabled bool)	Enable or disable preview mode for draft content

API methods

All methods return Go structs with the response data and an error.

Pages

Retrieve and search pages created in the ButterCMS dashboard.

package main

import (
    "fmt"
    "github.com/buttercms/buttercms-go"
)

func main() {
    ButterCMS.SetAuthToken("your_api_token")

    // Build query parameters
    params := map[string]string{
        "locale":   "en",
        "preview":  "1",
        "levels":   "2",
    }

    // Fetch a single page
    page, err := ButterCMS.GetPage("landing_page", "home-page", params)
    if err != nil {
        panic(err.Error())
    }
    fmt.Printf("Page: %+v\n", page)

    // Fetch list of pages
    listParams := map[string]string{
        "page":      "1",
        "page_size": "10",
        "locale":    "en",
    }
    pages, err := ButterCMS.GetPages("landing_page", listParams)
    if err != nil {
        panic(err.Error())
    }
    fmt.Printf("Pages: %+v\n", pages)
}

Collections

Fetch content from Collections (structured data tables).

// Build parameters
params := map[string]string{
    "locale": "en",
}

// Fetch collection content
// Pass collection keys as a slice
content, err := ButterCMS.GetContentFields([]string{"faq", "navigation"}, params)
if err != nil {
    panic(err.Error())
}

fmt.Printf("Content: %+v\n", content)

Blog Posts

Access the built-in Blog Engine for posts, categories, tags, and authors.

// List blog posts
params := map[string]string{
    "page":         "1",
    "page_size":    "10",
    "exclude_body": "true",
}

postsResp, err := ButterCMS.GetPosts(params)
if err != nil {
    panic(err.Error())
}

for _, post := range postsResp.Data {
    fmt.Printf("Title: %s\n", post.Title)
    fmt.Printf("Slug: %s\n", post.Slug)
}

// Fetch a single post
post, err := ButterCMS.GetPost("my-post-slug")
if err != nil {
    panic(err.Error())
}
fmt.Printf("Post title: %s\n", post.Data.Title)
fmt.Printf("Post body: %s\n", post.Data.Body)

// Search posts
searchParams := map[string]string{
    "query":     "search term",
    "page":      "1",
    "page_size": "10",
}
results, err := ButterCMS.SearchPosts("search term", searchParams)
if err != nil {
    panic(err.Error())
}
fmt.Printf("Search results: %+v\n", results)

Authors

// Build parameters
params := map[string]string{
    "include": "recent_posts",
}

// List all authors
authorsResp, err := ButterCMS.GetAuthors(params)
if err != nil {
    panic(err.Error())
}

for _, author := range authorsResp.Data {
    fmt.Printf("Author: %s %s\n", author.FirstName, author.LastName)
}

// Fetch a single author
author, err := ButterCMS.GetAuthor("jennifer-smith", params)
if err != nil {
    panic(err.Error())
}
fmt.Printf("Author bio: %s\n", author.Data.Bio)

Categories

params := map[string]string{
    "include": "recent_posts",
}

// List all categories
categoriesResp, err := ButterCMS.GetCategories(params)
if err != nil {
    panic(err.Error())
}

for _, category := range categoriesResp.Data {
    fmt.Printf("Category: %s (%s)\n", category.Name, category.Slug)
}

// Fetch a single category
category, err := ButterCMS.GetCategory("news", params)
if err != nil {
    panic(err.Error())
}
fmt.Printf("Category: %+v\n", category)

Tags

params := map[string]string{
    "include": "recent_posts",
}

// List all tags
tagsResp, err := ButterCMS.GetTags(params)
if err != nil {
    panic(err.Error())
}

for _, tag := range tagsResp.Data {
    fmt.Printf("Tag: %s\n", tag.Name)
}

// Fetch a single tag
tag, err := ButterCMS.GetTag("featured", params)
if err != nil {
    panic(err.Error())
}
fmt.Printf("Tag: %+v\n", tag)

Feeds

Retrieve RSS, Atom, and Sitemap feeds.

// Get RSS feed
rssFeed, err := ButterCMS.GetFeed("rss")
if err != nil {
    panic(err.Error())
}
fmt.Printf("RSS Feed: %s\n", rssFeed)

// Get Atom feed
atomFeed, err := ButterCMS.GetFeed("atom")
if err != nil {
    panic(err.Error())
}

// Get Sitemap
sitemap, err := ButterCMS.GetFeed("sitemap")
if err != nil {
    panic(err.Error())
}

Query parameters reference

Parameter	Applies To	Description
page	Posts, Pages	Page number for pagination
page_size	Posts, Pages	Number of items per page
exclude_body	Posts	Exclude post body ("true" or "false")
author_slug	Posts	Filter posts by author
category_slug	Posts	Filter posts by category
tag_slug	Posts	Filter posts by tag
include	Authors, Categories, Tags	Set to "recent_posts" to include posts
locale	Pages, Collections	Locale code for localized content
preview	Pages	Set to "1" for draft content
levels	Pages	Depth of nested references (1–3)

Complete example

package main

import (
    "fmt"
    "os"

    "github.com/buttercms/buttercms-go"
)

func main() {
    // Initialize with API token from environment
    apiToken := os.Getenv("BUTTERCMS_API_TOKEN")
    ButterCMS.SetAuthToken(apiToken)

    // Fetch homepage data
    homeData, err := fetchHomepageData()
    if err != nil {
        fmt.Printf("Error fetching homepage: %v\n", err)
        return
    }

    fmt.Printf("Page loaded: %+v\n", homeData.Page)
    fmt.Printf("Navigation items: %d\n", len(homeData.Navigation))
    fmt.Printf("Recent posts: %d\n", len(homeData.RecentPosts))
}

type HomepageData struct {
    Page        interface{}
    Navigation  interface{}
    RecentPosts interface{}
}

func fetchHomepageData() (*HomepageData, error) {
    // Fetch the home page
    pageParams := map[string]string{"locale": "en"}
    page, err := ButterCMS.GetPage("landing_page", "home", pageParams)
    if err != nil {
        return nil, fmt.Errorf("failed to fetch page: %w", err)
    }

    // Fetch navigation collection
    navParams := map[string]string{}
    navigation, err := ButterCMS.GetContentFields([]string{"main_navigation"}, navParams)
    if err != nil {
        return nil, fmt.Errorf("failed to fetch navigation: %w", err)
    }

    // Fetch recent blog posts
    postParams := map[string]string{
        "page":         "1",
        "page_size":    "3",
        "exclude_body": "true",
    }
    posts, err := ButterCMS.GetPosts(postParams)
    if err != nil {
        return nil, fmt.Errorf("failed to fetch posts: %w", err)
    }

    return &HomepageData{
        Page:        page,
        Navigation:  navigation,
        RecentPosts: posts.Data,
    }, nil
}

Resources

GitHub Repository

View source code, report issues, and contribute

Go Packages

Package documentation and reference