Skip to content

SDKs

The official Go SDK gives you a typed, idiomatic client for the managed.dev API. Its wire types are generated from the same OpenAPI spec that defines the API — a CI drift gate regenerates them and fails the build if the SDK and spec ever disagree — with a curated, hand-written surface on top. The mf CLI is built on it, so the SDK is exercised by every CLI release.

TypeScript and PHP SDKs are designed but not yet shipped — see the roadmap below.

The SDK is a thin, typed wrapper over https://api.managed.dev/v1 — not a second product with its own concepts. Everything you can do with cURL you can do with the SDK, plus the ergonomics you’d expect from a PaaS client:

Typed everywhere

Every resource, parameter, and the response envelope are typed. Twenty-one services — Sites, Environments, Deployments, Jobs, Webhooks, and the rest — mirror the API’s resource areas.

Auto-pagination

Lists return Page[T] — range .Iter(ctx) or call .All(ctx) and cursor pagination is handled for you, page by page as you go.

Idempotent retries

The client attaches an Idempotency-Key to every POST and retries 429/5xx/transport failures with exponential backoff, honoring Retry-After — a retry replays the original job instead of creating a second one.

Typed errors

The error envelope surfaces as *forge.Error carrying Type, Code, Param, RequestID, and DocURL, with predicates like NotFound() and RateLimited() — match on the code, don’t parse strings.

Job helpers

Jobs.Wait, WaitSuccess, Stream, and Follow take an async job to a terminal state — Follow streams over SSE with a polling fallback, and the Success variants return a typed *forge.JobError when the job fails.

Pinned version

The client sends Forge-Version: 2026-06-23 — the API version it was built against — so an additive API change never silently shifts a payload under you.

It also ships forge.VerifyWebhookSignature for webhook verification and a forgetest package — an in-process fake API server for your tests, with self-advancing jobs and canned errors. Dependencies: the standard library plus google/uuid, nothing else.

go get
go get terriblegit.com/terrible/forge-go

Construct a client with an API key, then call a resource. This lists your sites — a sites:read call — iterating every page:

main.go
package main
import (
"context"
"fmt"
"os"
forge "terriblegit.com/terrible/forge-go"
)
func main() {
ctx := context.Background()
client := forge.New(os.Getenv("FORGE_TOKEN"))
page, err := client.Sites.List(ctx, nil)
if err != nil {
if apiErr, ok := forge.AsError(err); ok {
fmt.Fprintf(os.Stderr, "api error %s (%s): %s\n", apiErr.Code, apiErr.Type, apiErr.Message)
os.Exit(1)
}
panic(err)
}
// Iter fetches each next page lazily as you range.
for site, err := range page.Iter(ctx) {
if err != nil {
panic(err)
}
fmt.Printf("%s %s %s\n", site.ID, site.Domain, site.Status)
}
}

Most mutations return 202 Accepted and a *forge.Job. Jobs.FollowSuccess streams progress to a writer and returns a typed *forge.JobError if the job ends in failed; Jobs.WaitSuccess does the same without the output stream. This kicks off a build and follows it:

build-and-follow.go
job, err := client.Deployments.CreateBuild(ctx, siteID, envID, forge.BuildCreateParams{
Builder: "wordpress",
})
if err != nil {
return err
}
done, err := client.Jobs.FollowSuccess(ctx, job.ID, os.Stdout)
if err != nil {
var jobErr *forge.JobError
if errors.As(err, &jobErr) {
return fmt.Errorf("build failed: %s", jobErr.Job.Error.Message)
}
return err
}
fmt.Printf("build %s: %s\n", done.ID, done.Status)

Job statuses are exactly queued, running, succeeded, and failed; forge.JobTerminal(job) tells you whether one is done.

Options are functional and composable:

configured-client.go
client := forge.New(os.Getenv("FORGE_TOKEN"),
forge.WithAPIVersion("2026-06-23"),
forge.WithMaxRetries(3), // default 2
forge.WithUserAgent("myapp/1.0"),
forge.WithBaseURL("https://api.managed.dev/v1"),
)

forge.WithoutAutoIdempotency() disables the automatic Idempotency-Key; to pin a specific key for one request, wrap the context with forge.WithIdempotencyKey(ctx, key). The default request timeout is 30 seconds (streaming calls have none — cancel via the context), and the client is safe for concurrent use.

forge.VerifyWebhookSignature checks a Forge-Signature header — HMAC and timestamp — in one call:

webhook-handler.go
err := forge.VerifyWebhookSignature(payload, r.Header.Get("Forge-Signature"),
os.Getenv("WEBHOOK_SECRET"), forge.DefaultWebhookTolerance)
if err != nil {
http.Error(w, "bad signature", http.StatusUnauthorized)
return
}

forgetest spins up an in-process fake of the API so your tests don’t need a network or a key:

client_test.go
srv := forgetest.NewServer(t)
srv.Job("job_01J9F2KQ", "running", "succeeded") // self-advances on each poll
job, err := srv.Client.Backups.Create(ctx, "site_01J7QZ3M")
done, err := srv.Client.Jobs.WaitSuccess(ctx, job.ID, nil)

srv.Data, srv.List, and srv.Error stub canned responses for any route, and srv.Requests() returns what your code actually sent.

Preview TypeScript and PHP SDKs are designed to come off the same generation pipeline as the Go SDK, with the same shape — auto-pagination, idempotent retries, typed errors, job helpers. They have not shipped; there is no package to install today.