Using the API

API overview

The Plany API: gRPC services, one endpoint each, and the clients that call them.

Everything the console, the plany CLI and the Terraform provider do goes through the Plany API, so anything you can do there you can do from your own code.

The API is gRPC, defined in Protocol Buffers. It follows the Google API Improvement Proposals and reuses googleapis types rather than inventing its own: resource names follow AIP-122, long-running work returns google.longrunning.Operation, money is google.type.Money, time ranges are google.type.Interval, and errors carry google.rpc details.

Calling it

export PLANY_API_KEY=pk_...
plany playpute servers list --project  --region

The Go SDK, github.com/plany-cloud/apis/sdk/go, presents your key on every call. For another language, generate a client from the published schema (below).

The endpoint

Every service answers at one address:

text

api.plany.cloud:443

It is TLS only, and every call carries your API key as authorization: Bearer <api key> — see Authentication. A call is routed by the service named in its method, so one connection reaches every service below.

Regional resources name their region in the resource name — projects/{project}/locations/eu-west-2/.... eu-west-2 is the region Plany serves. See Regions.

Service	What it is for	Guide
`plany.playpute.v1.PlayputeService`	Game servers, autoscaling groups, schematics, allocation	Playpute
`plany.game.v1.GameRegistryService`	Games and builds	Game Registry
`plany.gamelog.v1.LogService`	What servers and sandboxes printed	Game logs
`plany.gamelog.v1.EventService`	How far player detection has got for a game	Reference
`plany.session.v1.PlayerSessionService`	Who is playing, and who was	Players
`plany.sandbox.v1.SandboxService`	Sandboxes, revisions and triggers	Sandbox
`plany.agones.v1.AutopilotService`	Agones Autopilot fleets and allocation	Agones Autopilot
`plany.encore.v1.EncoreService`	Encore	Encore
`plany.secret.v1.SecretService`	Secrets	Reference
`plany.containerregistry.v1.RegistryService`	Container Registry repositories and credentials	Reference
`plany.vpc.v1.VpcService`	Networks and firewall rules	Networks
`plany.iam.v1.IamService`	Roles, API keys, service accounts	IAM
`plany.account.v1.AccountService`	Your account and its members	Accounts
`plany.project.v1.ProjectService`	Projects	Projects
`plany.billing.v1.BillingService`	Prices, balance and costs	Billing
`plany.quota.v1.QuotaService`	Limits, and asking for more	Quotas
`plany.audit.v1.AuditService`	Your activity log	Activity
`plany.support.v1.SupportService`	Support cases	Support

Long-running operations are followed with google.longrunning.Operations at the same address. See Operations.

Getting the schema

The public schema is a buf module, github.com/plany-cloud/apis, holding exactly the services, methods, messages and fields in the reference. It declares the googleapis dependency it imports, so generating a client is one command:

Shell

buf generate --template buf.gen.yaml

A client generated from it uses the same field numbers as the servers, so it is wire-compatible with the API.

Calls that need no credential

Pricing is readable before you have an account: BillingService/ListPlans, ListSkus and EstimateCost answer without a credential, as does IamService/IssueToken, which is how a credential is obtained. Nothing that changes anything is in that set.

Read on

Reference

Every method, message and field, generated from the schema itself.

Authentication

Creating an API key and presenting it.

Conventions

Names, pagination, field masks, etags, request ids.

Operations

Long-running work and how to follow it.

Errors

Status codes, and the details that make a refusal actionable.