Build on Chief — MCP server, REST API, and CLI

chief-go is the official Go client for the Chief API. Use it to build Chief into a Go service or automation: start chats over your project, upload and label assets, schedule actions, and page through results with typed methods instead of hand-rolled HTTP. It’s also the foundation the chief CLI and MCP server are built on — so anything they do, you can do directly in Go. It depends only on the standard library, so you can vendor it into external tools without pulling in third-party packages.

Install

go get github.com/Storytell-ai/chief-go/chief

Requirements

Go 1.26 or newer. The client depends only on the standard library, so it adds no third-party transitive dependencies to your module.

Credentials

A Personal Access Token is required and sent as the X-API-Key header. Most routes are project-scoped and also need a project id (X-Project-Id). The Projects.List call is the exception — it works with only an API key and returns the projects the key can reach. Create a token in the Chief app under Settings → API tokens — see Introduction for details on tokens and project ids. Pass credentials as options or let the client read them from the environment:

Option	Environment variable	Required
`WithAPIKey`	`CHIEF_API_KEY`	yes
`WithProjectID`	`CHIEF_PROJECT_ID`	for project-scoped routes
`WithBaseURL`	`CHIEF_BASE_URL`	no (defaults to `https://api.storytell.ai`)

Resources

Each resource is its own service on the client: client.Chats, client.Assets, client.Labels, client.Actions, client.Sessions, client.Skills, client.Memories, and client.Projects.

Chats

Chat turns run asynchronously: Create and SendMessage return as soon as the workflow is accepted. WaitForResponse polls GetMessage until the turn finishes — or call GetMessage directly to poll on your own schedule.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/Storytell-ai/chief-go/chief"
)

func main() {
	client, err := chief.New(
		chief.WithAPIKey(os.Getenv("CHIEF_API_KEY")),
		chief.WithProjectID(os.Getenv("CHIEF_PROJECT_ID")),
	)
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	// Open a chat with its first turn; the turn runs asynchronously.
	created, err := client.Chats.Create(ctx, &chief.CreateChatRequest{
		Prompt: "What changed in the codebase this week?",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Block until the response is populated.
	msg, err := client.Chats.WaitForResponse(ctx, created.ChatID, created.MessageID, 2*time.Minute)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("answer: %s\n", msg.Response)

	// Ask a follow-up in the same chat.
	sent, err := client.Chats.SendMessage(ctx, created.ChatID, &chief.SendMessageRequest{
		Prompt: "Now summarize that in one sentence.",
	})
	if err != nil {
		log.Fatal(err)
	}

	follow, err := client.Chats.WaitForResponse(ctx, created.ChatID, sent.MessageID, 2*time.Minute)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("follow-up: %s\n", follow.Response)
}

Assets

UploadFile runs the full three-step flow — create the asset row, PUT the bytes to the signed URL, then complete the upload to start ingest. The returned bool is true when the content was a dedup hit and no bytes were uploaded.

// Upload a local file, then block until ingest reaches a terminal status.
asset, deduped, err := client.Assets.UploadFile(ctx, "report.pdf")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("asset %q (dedup hit: %t)\n", asset.AssetID, deduped)

asset, err = client.Assets.WaitForReady(ctx, asset.AssetID, 2*time.Minute)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("status: %s\n", asset.Status)

// Attach a label by name; an unmatched name is auto-created.
label, err := client.Assets.AttachLabel(ctx, asset.AssetID, "quarterly")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("attached label %q (%s)\n", label.Name, label.LabelID)

// List the assets in the project.
page, err := client.Assets.List(ctx, chief.WithLimit(10))
if err != nil {
	log.Fatal(err)
}
for _, a := range page.Data {
	fmt.Printf("%s\t%s\t%s\n", a.AssetID, a.Status, a.Filename)
}

Actions

Actions run a prompt on a schedule or in response to events, optionally emailing the result.

// An action that runs every day at 09:00 and emails its result.
action, err := client.Actions.Create(ctx, &chief.ActionRequest{
	Name:   "daily-digest",
	Prompt: "Summarize assets added to the project in 5 bullet points",
	Schedule: &chief.ScheduleRequest{
		Hour:     "9",
		Weekday:  "*",
		MonthDay: "*",
		Timezone: "America/Sao_Paulo",
	},
	Email: &chief.EmailOutcome{
		To:                   []string{"team@example.com"},
		Subject:              "Daily digest",
		IncludeDateInSubject: true,
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("created action %q\n", action.ActionID)

// Pause it, then resume it.
_, _ = client.Actions.Disable(ctx, action.ActionID)
_, _ = client.Actions.Enable(ctx, action.ActionID)

Pagination

List calls are cursor-paginated. Size a page with WithLimit, then feed the page’s LastID to WithAfterID to fetch the next one until HasMore is false:

var after string
for {
	opts := []chief.ListOption{chief.WithLimit(50)}
	if after != "" {
		opts = append(opts, chief.WithAfterID(after))
	}

	page, err := client.Assets.List(ctx, opts...)
	if err != nil {
		log.Fatal(err)
	}
	for _, a := range page.Data {
		fmt.Println(a.AssetID)
	}

	if !page.HasMore {
		break
	}
	after = page.LastID
}

WithBeforeID pages backward instead. The two cursors are mutually exclusive.

Errors

Every non-2xx response is returned as an *APIError carrying the HTTP status, a stable machine-readable Code, and a user-facing Humane message. Helpers cover the common cases:

session, err := client.Sessions.Get(ctx, "missing-id")
if err != nil {
	switch {
	case chief.IsNotFound(err):
		// 404
	default:
		if apiErr, ok := chief.IsAPIError(err); ok {
			log.Printf("chief: %s (%s)", apiErr.Humane, apiErr.Code)
		}
	}
}

Debugging

Pass WithDebug(true) when building the client to dump every HTTP request and response to the standard logger:

client, err := chief.New(
	chief.WithAPIKey(os.Getenv("CHIEF_API_KEY")),
	chief.WithProjectID(os.Getenv("CHIEF_PROJECT_ID")),
	chief.WithDebug(true),
)

Versioning

The package follows semantic versioning. Pin a version in your go.mod and review the release notes before upgrading across a major version:

go get github.com/Storytell-ai/chief-go/chief@latest

Reference

Package documentation — pkg.go.dev/github.com/Storytell-ai/chief-go/chief
Source and releases — github.com/Storytell-ai/chief-go

Overview

CLI

Go SDK

Go SDK

Install

Requirements

Credentials

Resources

Chats

Assets

Actions

Errors

Debugging

Versioning

Reference

​Install

​Requirements

​Credentials

​Resources

​Chats

​Assets

​Actions

​Pagination

​Errors

​Debugging

​Versioning

​Reference

Install

Requirements

Credentials

Resources

Chats

Assets

Actions

Pagination

Errors

Debugging

Versioning

Reference