at.happyproto.server.createInstance

Create an instance for the caller, and start a job that follows its provisioning. Customers only.

Repository @happyproto.at did:plc:mo7vq4jbioxwafy5zkcc3eux namespace authority

Details · procedure

Kind	procedure
Authority	server.happyproto.at
Indexed	11d ago · 2026-10-31

Showing version bafyreidwgliw6s6i54osalnflyta7v6spfvrnf2bwnwm3j3bcfblvgxfbm. Show the latest

Compare Edit in builder → Fork →

Procedure

procedure · POST

Input

application/json

idempotencyKey

requiredstring

A UUID the client generates once per intended change and resends on every retry of it, so a retry gets the original reply instead of acting twice.

plan

requiredstring

The plan's id, from at.happyproto.server.listPlans.

slug

requiredstring

The instance's subdomain: 3 to 32 of a-z, 0-9 and -, starting with a letter.

terms

ref

The beta terms the caller accepted with the create form's checkbox. The provisioner refuses a create without it (TermsRequired), staff included; it is optional here only so clients can start sending it before the provisioner requires it.

Reference

#termsAcceptance

Output

application/json

instance

requiredref

Reference

#instance

jobId

requiredstring

The background job following the change. Poll it with at.happyproto.server.getJob.

Errors

AuthRequired

This endpoint requires an authenticated caller.

Forbidden

The caller is not a HappyProto customer, or the provisioner refused them.

InvalidRequest

slug, plan or idempotencyKey is missing or malformed.

NotFound

Passed through from the provisioner.

InvalidSlug

Passed through from the provisioner: it reserves slugs by configuration as well.

SlugTaken

Passed through from the provisioner.

NotEntitled

Passed through from the provisioner.

InstanceLimit

Passed through from the provisioner.

NoCapacity

Passed through from the provisioner.

OperationInProgress

Passed through from the provisioner: the instance is already changing, or a request with this idempotencyKey is still running.

TermsRequired

The create carried no acceptance of the beta terms, or one without its wording.

TermsOutdated

The accepted terms are no longer the ones in force: reload and accept the current ones.

Upstream

The provisioner is unreachable, not configured, or answered with an error it does not explain to callers, or the job could not be started.

#availableVersion

object

A newer HappyView release the instance can upgrade to.

Properties

label

string

The HappyView version the release carries, e.g. 3.0.0-alpha.41, when known.

releasedAt

requiredstring · datetime

When HappyProto first offered it.

version

requiredstring

The release to pass to at.happyproto.server.upgradeInstance.

#instance

object

A customer's HappyView instance. Never carries the provisioner's placement or internal fields.

Properties

availableVersion

ref

A newer release, when one is on offer.

Reference

#availableVersion

createdAt

requiredstring · datetime

id

requiredstring

A UUID.

operation

ref

The change in progress, if any.

Reference

#operation

plan

requiredstring

The plan's id.

slug

requiredstring

state

requiredstring

knownValues: provisioning | running | stopped | failed | deleting

url

requiredstring · uri

version

requiredstring

The HappyView release it runs.

versionLabel

string

The HappyView version the release carries, e.g. 3.0.0-alpha.41, when known.

#operation

object

Properties

error

string

The provisioner's error code, when it failed.

id

requiredstring

kind

requiredstring

knownValues: create | update | upgrade | stop | start | destroy

status

requiredstring

knownValues: pending | running | succeeded | failed

step

string

The step it last reached.

#termsAcceptance

object

An acceptance of the beta terms, recorded append-only by the provisioner with the caller's DID.

Properties

termsVersion

requiredstring

The terms in force, e.g. beta-2026-11. Anything else is TermsOutdated.

maxLength: 64

text

requiredstring

The exact wording the caller ticked.

maxLength: 1000

textVersion

requiredstring

The version of the checkbox's wording.

maxLength: 32

Similar lexicons

semantic match

Lexicons whose schemas describe something close to this one. Check them before publishing a new one that overlaps.

at.happyproto.server.getInstance
query

One of the caller's own instances. Customers only.
at.happyproto.server.startInstance
procedure

Start one of the caller's instances, and start a job that follows the start. Customers only.
at.happyproto.server.updateInstance
procedure

Move one of the caller's instances to another plan or HappyView release, and start a job that follows the change. Customers only.
at.happyproto.server.upgradeInstance
procedure

Upgrade one of the caller's instances to the newer HappyView release its availableVersion offers, and start a job that follows the upgrade. The instance is offline for about 30 seconds; its database is snapshotted first, and a release that does not come up healthy is rolled back. Customers only.
at.happyproto.server.listInstances
query

The caller's own instances. Customers only.