Sign in
internal
workspaces

Provision Workspace

Provision a new workspace end-to-end with a Neon sandbox + counties.

Replaces the legacy bare-create POST /. A workspace granted no counties has zero geographic query access, so provisioning is the only sanctioned create path. Fires the stand_up_workspace Dagster job and returns once the rows are persisted (5-15s for Neon create).

A local workspace seeds its county rows claimed for the loader, and its county data loads asynchronously thereafter. A commons workspace is thin: its rows record the grant, no county load is queued, and the counties are available as soon as the call returns.

post/api/v1/internal/workspaces/provision

Request body

namestring required
initial_creditsinteger
region_idstring nullable
icp_category_idstring uuid nullable

Optional ICP category to assign at creation. Omit or pass null to leave the workspace unassigned.

county_data_residency'local' | 'commons'

Where a workspace's county data physically lives.

Orthogonal to WorkspaceType, which is a billing cohort: a discovery workspace and a thin workspace are independent facts, and folding one into the other would conflate plan with topology.

LOCAL is every deployed workspace: the counties it may query were copied into its own branch, so a statement over them is workspace-only. COMMONS is a thin workspace, whose branch holds none of them — it is entitled to counties the shared corpus holds, and that entitlement is what binds its model-authored statements to the commons router.

is_internalboolean

Mark the new workspace as a MAIA-staff workspace.

Response

Successful Response

idstring uuid required
namestring required
budget_authority'credits' | 'paid_balance' required

Which budget a metered run draws down.

Two members, because there are two budgets. Free usage and paid usage are the same balance on the same account, spent at the same prices and refused by the same check; what a workspace paid for that balance decides what its refusal offers next, not how the run is admitted. A third member for the free tier is what let the two drift — different prices, different exemptions, different per-run sizing — while both claimed to meter usage.

avatar_colorstring nullable required
available_enrichment_creditsinteger required
used_enrichment_creditsinteger required
remaining_creditsinteger required
is_suspendedboolean required
is_internalboolean required
county_coverage'granted' | 'national' required

Which counties a workspace may open projects on.

GRANTED is the counties its workspace_counties rows grant. NATIONAL is every county the shared corpus holds, for a workspace whose data is served from the corpus; a workspace still on its own branch reads only what that branch holds, so national coverage widens nothing for it until it moves. Stored so every gate reads one column; its value is a copy of the billing account's paid access, written only by the billing writes.

county_data_residency'local' | 'commons' required

Where a workspace's county data physically lives.

Orthogonal to WorkspaceType, which is a billing cohort: a discovery workspace and a thin workspace are independent facts, and folding one into the other would conflate plan with topology.

LOCAL is every deployed workspace: the counties it may query were copied into its own branch, so a statement over them is workspace-only. COMMONS is a thin workspace, whose branch holds none of them — it is entitled to counties the shared corpus holds, and that entitlement is what binds its model-authored statements to the commons router.

reads_entire_corpusboolean required

The entitlement model's corpus verdict, resolved once here: national coverage on the shared-corpus lane. Not county_coverage == 'national' — a national workspace still on its own branch reads only the counties loaded into that branch. Carries the same value the customer-facing national_county_coverage does.

origin'staff' | 'self_serve_discovery' | 'direct_paid' required

Which door a workspace was acquired through.

An acquisition fact, written once at creation and never rewritten. Orthogonal to WorkspaceType, which is the billing cohort, and to CountyDataResidency, which is topology: a direct-paid workspace opens as a discovery-type workspace on the joining grant and converts in place, so the type says nothing about the door. Keeping it separate is what makes an abandoned direct signup countable — it holds a free workspace whose type is indistinguishable from a Discovery one.

STAFF is every workspace a person at MAIA provisioned, and is what a row written before this column reports.

icp_category_idstring uuid nullable required
member_countinteger required
project_countinteger required
created_atstring date-time nullable required
updated_atstring date-time nullable required

Changes