Go

github.com/arcarolabs/operate-as-go is the official Go library. It needs Go 1.21 or newer and has no dependencies beyond the standard library. Each service's actions come typed in a module of their own, such as github.com/arcarolabs/operate-as-go/services/sheets: get the ones you use.

Get startedCopy Anchor Link

go get github.com/arcarolabs/operate-as-go github.com/arcarolabs/operate-as-go/services/sheets

import (
	operateas "github.com/arcarolabs/operate-as-go"
	"github.com/arcarolabs/operate-as-go/services/sheets"
)

export OPERATE_AS_API_KEY="oa_..."

operate := operateas.New(os.Getenv("OPERATE_AS_API_KEY"))

reporting := operateas.New(os.Getenv("OPERATE_AS_REPORTING_KEY")) // reads sheets for the weekly report
bookings := operateas.New(os.Getenv("OPERATE_AS_BOOKINGS_KEY"))   // writes to one client's calendar

svc := sheets.New(operate, "6f1c2a7e-...") // one of your clients, by id
rows, err := svc.ReadRows(ctx, sheets.ReadRowsInput{SpreadsheetID: "1BxiM...", Range: "A1:D20"})
if err != nil {
	return err
}
fmt.Println(rows.Status, string(rows.Data))

clients, err := operate.Clients.List(ctx, nil)
if err != nil {
	return err
}
for _, c := range clients {
	fmt.Println(c.ID, c.Name, c.Services) // 6f1c2a7e-... Miller Dental [sheets slack]
}

OptionsCopy Anchor Link

operate := operateas.New(os.Getenv("OPERATE_AS_API_KEY"),
	operateas.WithBaseURL("https://api.operate.as"), // or set OPERATE_AS_BASE_URL
	operateas.WithTimeout(30*time.Second),           // default 60s
	operateas.WithHTTPClient(&http.Client{}),        // your own transport
)

Service modulesCopy Anchor Link

Every service with actions has a typed module: github.com/arcarolabs/operate-as-go/services/<package>, where the package is the service's name without dashes, such as aiinbx for AI Inbx. Each has New and For, and each action as a method:

inbox := aiinbx.New(operate, clientID)
_, err := inbox.ReplyToEmail(ctx, aiinbx.ReplyToEmailInput{
	EmailID: emailID,
	Body:    &aiinbx.ReplyToEmailBody{From: "kate@millerdental.com", HTML: "<p>Thanks for booking!</p>"},
})
if err != nil {
	return err
}

rows, err := sheets.New(operate, clientID).ReadRows(ctx, sheets.ReadRowsInput{SpreadsheetID: "1BxiM...", Range: "A1:D20"})

Every input is a struct with documented fields, so the compiler catches a misspelled field or a wrong type. Optional fields are pointers: set one with operateas.Ptr(20). Each module also has Request for any endpoint of the service's own API.

Each integration's page in these docs names its module. A module's version moves on when its service's actions change. Without a module, operate.Service(clientID, "sheets").Run(ctx, "read_rows", input) runs any action.

Actions and pass-throughCopy Anchor Link

svc := sheets.New(operate, clientID)
rows, err := svc.ReadRows(ctx, sheets.ReadRowsInput{SpreadsheetID: "1BxiM...", Range: "A1:D20"})
if err != nil {
	return err
}

var sheet struct {
	Values [][]string `json:"values"`
}
if err := rows.Decode(&sheet); err != nil {
	return err
}
fmt.Println(rows.Status, sheet.Values)

The resultCopy Anchor Link

Run and Request return a *Result:

When the service answers with a file, result.Encoding is "base64" and Data holds the file as a base64 JSON string. Decode it into a string, then base64.StdEncoding.DecodeString it. Encoding is "json" for parsed JSON and "text" for plain text. See The result.

if !rows.OK() {
	return fmt.Errorf("sheets said %d: %s", rows.Status, rows.Data)
}

ErrorsCopy Anchor Link

Check errors with the helpers, which work on wrapped errors too:

The *operateas.Error itself has:

Other statuses come back as an *Error no helper reports: check StatusCode. Errors building or decoding a request, such as a body that won't marshal or an unknown method, are plain errors, not *Error.

Catch reconnect-requiredCopy Anchor Link

A client's access ending won't fix itself. Catch it, tell someone, and stop working for that client:

_, err := svc.AddRow(ctx, sheets.AddRowInput{
	SpreadsheetID: "1BxiM...",
	Range:         "A1",
	Values:        []any{"2026-10-16", "Jane Doe"},
})

var apiErr *operateas.Error
switch {
case err == nil:
case operateas.IsReconnectRequired(err):
	errors.As(err, &apiErr)
	notifyTeam(clientID + ": " + apiErr.Detail) // "...Send them their link to reconnect."
	pauseWorkflow(clientID)
case operateas.IsRateLimited(err):
	errors.As(err, &apiErr)
	time.Sleep(apiErr.RetryAfter)
case operateas.IsServiceUnavailable(err):
	retryLater()
default:
	return err
}

See Retries for what's worth retrying.

Verify webhooksCopy Anchor Link

VerifyWebhook(payload, header, secret, tolerance) checks the Operate-As-Signature header and returns the *Event. Read the raw body first:

http.HandleFunc("/hooks/operate-as", func(w http.ResponseWriter, r *http.Request) {
	payload, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "unreadable body", http.StatusBadRequest)
		return
	}
	event, err := operateas.VerifyWebhook(payload, r.Header.Get(operateas.SignatureHeader),
		os.Getenv("OPERATE_AS_WEBHOOK_SECRET"), 0)
	if err != nil {
		http.Error(w, "bad signature", http.StatusBadRequest)
		return
	}

	if event.Type == operateas.EventConnectionExpired {
		emailClient(event.Data.ClientName, event.Data.ReconnectURL)
	}
	w.WriteHeader(http.StatusNoContent)
})

See Webhooks for the events.

TypesCopy Anchor Link

Result.Data is raw JSON because each service answers in its own shape. Decode it into a struct that matches the service's docs.