Conventions & catalog

Naming#

Function names are <namespace>.<action>. Namespaces are singular and lowerCamelCase — deployment, serviceAccount, workloadIdentity. Actions are short verbs:

For some resources a list item is a reduced, non-sensitive projection of what get returns, not the full resource — list is an index, get is the detail. Most notably deployment.list omits the environment, mounted files, command/args, annotations and the signed log URLs (read them with deployment.get), and envgroup.list returns a variable count rather than the values (read them with envgroup.get). This is an authorization boundary: deployment.list/envgroup.list can be granted without exposing secrets. See Roles & permissions.

Resources scoped to a location (deployments, domains, routes, disks, pull secrets, workload identities) take both project and location on every call. Project-only resources (roles, service accounts, env groups, audit-log) take only project.

Partial updates#

Most update calls replace the whole resource — pass the full desired state. A few resources have a partial-update model because the full state would be unwieldy to re-state on every change. The biggest one is deployment.deploy:

• env replaces all environment variables.
• addEnv / removeEnv operate on top of the previous revision’s env.
• envGroups replaces the list of group references.
• addEnvGroups / removeEnvGroups operate on top of the previous list.

This same model could appear on other functions in the future; assume replace by default unless the schema explicitly has an add* / remove* pair.

Pagination#

List endpoints return all items in one response today. If your project grows beyond a thousand or so of any resource type, expect pagination tokens to appear in the response — they’ll be added compatibly.

Idempotency#

create calls are idempotent on their (project[, location], name): a second call with the same identifier and the same spec returns success without creating a duplicate. A second call with a different spec is treated as an update of the existing resource (so be careful — there’s no “create only if not exists” mode).

Function catalog#

The big picture. Each row is a fully-qualified API function.

Identity#

Workspace#

Deployments#

Routing#

Storage and registry#

Access#

Billing#

GitHub#

For build-and-deploy from GitHub. These manage the link between a repository and the service account it deploys as.

The keyless token exchange and build/deploy status reporting (github.exchangeToken, github.notify) are authenticated by the workflow’s GitHub OIDC token and called by the build-and-deploy action, not directly.

Other#

Typed clients#

If you’re calling the API from Go, the github.com/deploys-app/api/client package wraps every function in a typed client — the same client the deploys CLI uses internally.

c := &client.Client{
    Auth: func(r *http.Request) {
        r.Header.Set("Authorization", "Bearer "+token)
    },
}
port := 8080
resp, err := c.Deployment().Deploy(ctx, &api.DeploymentDeploy{
    Project:  "acme",
    Location: "gke.cluster-rcf2",
    Name:     "web",
    Image:    "registry.deploys.app/acme/web:v2.4.1",
    Type:     api.DeploymentTypeWebService,
    Port:     &port,
})