SDKsGo
Go SDK
Install orbits-go, create a client, deploy and follow a build, manage variables and domains, and handle errors, pages and retries.
c, err := orbits.NewFromEnv()
if err != nil {
log.Fatal(err)
}
for p, err := range c.Projects.All(ctx, "my-team", nil) {
if err != nil {
log.Fatal(err)
}
fmt.Println(p.Slug, p.Status)
}orbits-go is the official Go library, with types generated from the API's OpenAPI contract. It has no dependencies outside the standard library, and needs Go 1.23 or later: lists and the build log are Go iterators. The Orbits CLI and MCP server are built on it.
team is a team's slug or team_ id, and project a project's slug or prj_ id.
Install
$ go get github.com/The-Orbits/orbits-goimport orbits "github.com/The-Orbits/orbits-go"Authenticate
Make an API token under Team › Settings › API tokens and put it in ORBITS_TOKEN. NewFromEnv reads it, and ORBITS_API_URL if it is set.
$ export ORBITS_TOKEN=orb_live_…Or pass the token yourself, with options:
c, err := orbits.New(token,
orbits.WithBaseURL("https://stagingapi.theorbits.app/v1"),
orbits.WithUserAgent("my-deployer/1.0"),
)| Option | What it does |
|---|---|
WithBaseURL(url) | The API's base URL, with /v1. Default https://api.theorbits.app/v1 |
WithUserAgent(product) | Puts your tool's name before the SDK's, like my-deployer/1.0 orbits-go/0.1.0. Settings › API tokens shows it as the token's last use |
WithHTTPClient(h) | Your *http.Client. Its Timeout bounds each attempt (default 60 seconds) |
WithMaxRetries(n) | Retries after the first try. Default 3; 0 turns them off |
WithHeader(k, v) | A header on every request |
Per call, orbits.WithIdempotencyKey(key), orbits.WithRequestHeader(k, v) and orbits.WithNoRetry() go after the other arguments.
The token is sent only in the Authorization: Bearer header. The SDK never logs it or variable values, and printing a Client doesn't show it. c.Me.Get(ctx) says who the token acts as.
Deploy and follow the build
For a Git project, Deployments.Create builds a branch's newest commit, by default the production branch:
package main
import (
"context"
"fmt"
"log"
orbits "github.com/The-Orbits/orbits-go"
)
func main() {
ctx := context.Background()
c, err := orbits.NewFromEnv()
if err != nil {
log.Fatal(err)
}
d, err := c.Deployments.Create(ctx, "my-team", "my-app", orbits.CreateDeploymentRequest{})
// or a preview: orbits.CreateDeploymentRequest{Branch: orbits.Ptr("feature/checkout")}
if err != nil {
log.Fatal(err)
}
for ev, err := range c.Deployments.StreamLogs(ctx, "my-team", "my-app", d.ID, nil) {
if err != nil {
log.Fatal(err)
}
if ev.Type == orbits.LogEventLine {
fmt.Println(ev.Line.Text)
}
}
final, err := c.Deployments.Wait(ctx, "my-team", "my-app", d.ID, nil) // *orbits.DeploymentError if it failed
if err != nil {
log.Fatal(err)
}
if final.URL != nil {
fmt.Println(*final.URL)
}
}StreamLogs yields line, steps and done events and stops after done; a finished build answers at once. When the connection drops, it reconnects from the last line it received, without gaps or repeats. ListLogs pages through a finished build's log instead. Deployments.Get(ctx, team, project, deployment) reads one deployment.
Deploy a folder
kind := orbits.ProjectSourceKindUpload
_, err := c.Projects.Create(ctx, "my-team", orbits.ProjectCreate{Name: "my-site", SourceKind: &kind})
if err != nil {
return err
}
d, err := c.Deployments.UploadDir(ctx, "my-team", "my-site", "./dist", nil)UploadDir zips the folder's contents, leaving out node_modules, .git, .next, __MACOSX, .DS_Store, .orbits and the patterns of the folder's .orbitsignore (.gitignore syntax). It refuses links and special files, and checks the limits (a zip of up to 100 MiB, 500 MiB and 20,000 files unpacked) before sending anything. Then it sends the zip straight to storage, without your token, and returns the queued production deployment. UploadZip sends a zip you already have; ZipDir only builds one. Set UploadOptions.IdempotencyKey when you may retry the whole deploy, so a retry gets the same upload instead of a second.
Only projects created with SourceKind: upload take uploads. A Git project deploys with Deployments.Create, Redeploy, or a push.
Promote, roll back, redeploy
_, err = c.Deployments.Promote(ctx, "my-team", "my-app", "dpl_…") // a preview to production, as a new build
_, err = c.Deployments.Rollback(ctx, "my-team", "my-app", "dpl_…") // at once, no build
_, err = c.Deployments.Redeploy(ctx, "my-team", "my-app", "dpl_…", orbits.RedeployRequest{UseCache: orbits.Ptr(false)})
_, err = c.Deployments.Cancel(ctx, "my-team", "my-app", "dpl_…")A rollback pauses automatic production deploys. See Deployments.
Environment variables
_, err = c.Env.Create(ctx, "my-team", "my-app", orbits.EnvVarCreate{
Variables: []orbits.EnvVarInput{
{Key: "STRIPE_SECRET_KEY", Value: os.Getenv("STRIPE_SECRET_KEY")}, // sensitive by default
{Key: "API_URL", Value: "https://api.example.com", Sensitive: orbits.Ptr(false),
Environments: []orbits.EnvironmentName{orbits.EnvironmentNameProduction}},
},
})
for v, err := range c.Env.All(ctx, "my-team", "my-app", nil) {
if err != nil {
return err
}
fmt.Println(v.Key, v.Environments, v.Sensitive)
}Variables are sensitive (write-only) unless Sensitive is false, and apply to production and preview unless you set Environments. With Create, a key that exists already is a conflict (orbits.IsConflict) and nothing is saved; Env.Set replaces existing keys instead. New values apply to deployments built afterwards, so redeploy to use them. Values are never listed; Env.Reveal reads one non-sensitive value and Env.Pull an environment's readable values, both with a full-access token. See Environment variables.
Domains
dom, err := c.Domains.Add(ctx, "my-team", orbits.AddDomainRequest{
Domain: "shop.example.com",
Project: orbits.Ptr("my-app"),
})
if err != nil {
return err
}
fmt.Println(dom.State)
dom, err = c.Domains.Check(ctx, "my-team", "shop.example.com") // look the DNS up again nowBranch serves a branch's newest preview instead of production, and To redirects to another hostname. RequiredRecord is the record to add at your DNS provider. Records on Orbits DNS are ListRecords, AddRecord, ReplaceRecord and DeleteRecord. See Custom domains.
Services
c.Me, c.Teams, c.Projects, c.Deployments, c.Env, c.Domains (with DNS records, checks, zone imports, email setup and branch addresses), c.Flags, c.Workflows, c.Alerts, c.Observability (runtime logs, metrics, Analytics, Speed Insights), c.Usage, c.Activity, c.Billing, c.Templates, c.Operations and c.Integrations. There is a c.Sandboxes too, but sandboxes are not available yet.
Request types follow the API's field names. Optional fields are pointers, and a nil one is not sent; orbits.Ptr sets one inline. Enums are typed string constants, such as orbits.ProjectSourceKindUpload. To send null (to clear a value), name the field in the request's NullFields:
_, err := c.Domains.Update(ctx, "my-team", "shop.example.com", orbits.UpdateDomainRequest{NullFields: []string{"to"}})Errors
Every API error is an *orbits.Error with Status, Title, Detail, RequestID, Code, Errors (the fields of a 422), RequiredPlan and Feature (on a 402), RetryAfter and RateLimitScope. Detail is plain language and safe to show.
p, err := c.Projects.Get(ctx, "my-team", "my-app")
switch {
case orbits.IsNotFound(err): // not there, or not in the token's team
case orbits.IsTokenRefused(err): // a read-only token, or something no token can do
case err != nil:
if e, ok := orbits.AsError(err); ok {
log.Printf("%s (request %s)", e.Detail, e.RequestID)
}
}Also IsValidation, IsRateLimited, IsForbidden, IsConflict, IsUnauthorized, IsPlanRequired, IsServerError and IsCode(err, "upload_incomplete"). Errors.
Pages
Paginated lists have a List that returns one page, with its NextCursor, and an All iterator over every item:
params := &orbits.ListDeploymentsParams{Environment: orbits.DeploymentEnvironmentProduction}
for d, err := range c.Deployments.All(ctx, "my-team", "my-app", params) {
if err != nil {
return err
}
fmt.Println(d.ID, d.State)
}Waiting
op, err := c.Projects.Delete(ctx, "my-team", "old-site")
if err != nil {
return err
}
_, err = c.Operations.Wait(ctx, op.ID, &orbits.WaitOptions{Timeout: 5 * time.Minute}) // *orbits.OperationError if it failed
_, err = c.Deployments.Wait(ctx, "my-team", "my-app", "dpl_…", &orbits.WaitOptions{Interval: 3 * time.Second})Operations.Wait polls an operation until it succeeds, and Deployments.Wait a deployment until it is ready. Both poll every 2 seconds unless Interval says otherwise. Timeout bounds the wait; with none, only ctx does. A failed or canceled deployment is a *orbits.DeploymentError, whose Deployment.Failure says why.
Idempotency and retries
Every POST carries an Idempotency-Key that its retries reuse, so a retry never makes a change twice. Connection errors and 429, 502, 503 and 504 are retried up to three times, with a growing, random wait, or after Retry-After when the API sends one. GET, PUT, DELETE and POST are retried; a PATCH only on 429, which the API answers before doing anything.
Calling any endpoint
For anything the typed methods don't cover, Do sends a raw call with the same auth, retries and errors:
var out map[string]any
err := c.Do(ctx, "GET", "/teams/my-team/projects", url.Values{"q": {"shop"}}, nil, &out)