project

Create Sandbox Project From Feature

Changed on Sep 25, 2026

Create a sandbox project from a confirmed resolved feature (address entry).

The create-flow inversion: unlike POST /sandbox (county picked first), the county scope is derived from the matched feature before the project's RLS role is provisioned. Two-phase — this handler derives scope, inserts the PENDING project + role synchronously, and enqueues the async layer seed; status flips to ready and the layer arrives via SSE.

No available_geographies 403: the matched feature is in-coverage by construction (the resolver only searched this workspace's loaded sandbox). Unknown feature_id → 404; a county somehow not loaded → 404 before any project row is inserted; a matched feature whose _county_fips is NULL/malformed (a sandbox data-integrity fault, not a caller error) → 422.

post/api/v1/project/sandbox/from-feature

Request

Base URL
https://api.maia-analytics.com (the document declares no server; this is the origin it was published from)
URL
https://api.maia-analytics.com/api/v1/project/sandbox/from-feature
Auth
HTTP bearer

Headers

Idempotency-Keystring nullable

Request body

source_table'parcel' | 'building' | 'place' | 'address' | 'school' required

The table a resolved feature lives in — what a caller pulls its data from, and the feature's kind. A text match in the address, place or school table resolves (point-in-feature) to a parcel/building; a parcel attribute match resolves to the parcel itself.

feature_idstring required

county_fipsstring required

knowledge_skill_workspace_idstring uuid nullable

Response

Successful Response

project_idstring uuid required

status'pending' | 'ready' | 'failed' | 'archived' required

Lifecycle status for a project.

Replaces the boolean is_created whose name implied "was created" (always True once inserted) but semantically meant "is ready for the dashboard to show." Promoting to an enum lets new states (FAILED, ARCHIVED) join without contorting the boolean.

PENDING: row inserted, sandbox resources not yet materialized
READY: resources in place; visible on dashboard
FAILED: build raised mid-flight (sandbox saga rollback uses hard-delete instead, so this state is reserved for future async build paths that can't roll back atomically)
ARCHIVED: user-archived; hidden by default