Skip to main content

​
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
FunctionDescription
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

ParameterApplies ToDescription
pagePosts, PagesPage number for pagination
page_sizePosts, PagesNumber of items per page
exclude_bodyPostsExclude post body ("true" or "false")
author_slugPostsFilter posts by author
category_slugPostsFilter posts by category
tag_slugPostsFilter posts by tag
includeAuthors, Categories, TagsSet to "recent_posts" to include posts
localePages, CollectionsLocale code for localized content
previewPagesSet to "1" for draft content
levelsPagesDepth 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