> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```bash theme={null}
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](https://buttercms.com/settings/).
```go theme={null}
package main
import (
"github.com/buttercms/buttercms-go"
)
func main() {
ButterCMS.SetAuthToken("your_api_token")
}
```
## Configuration options
```go theme={null}
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.
```go theme={null}
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).
```go theme={null}
// 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.
```go theme={null}
// 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
```go theme={null}
// 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
```go theme={null}
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
```go theme={null}
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.
```go theme={null}
// 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
```go theme={null}
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
View source code, report issues, and contribute
Package documentation and reference