Docs navigation

Developer Docs

Backend API

Contribution and lifecycle APIs, auth bridge, and OpenAPI entry points.

The FastAPI backend supports contribution staging, maintainer review, and the region-proposal lifecycle over a Postgres system of record.

Routes by router

Public (contribution)

  • POST /upload/token — Dedup-check a mesh and get a presigned HuggingFace upload URL.
  • POST /upload/submit — Stage the uploaded mesh and record the submission.
  • GET /upload/job/{job_id} — Check the status of a contributor's ingestion job.
  • POST /upload/job/{job_id}/cancel — Cancel an in-flight ingestion job.

Maintainer (contribution review)

  • GET /review-queue — List submissions awaiting maintainer review.
  • POST /approve — Approve a reviewed submission and move its registry pointer.
  • POST /reject — Decline a reviewed submission.

Maintainer (region lifecycle)

  • POST /region-lifecycles — Create a region planning lifecycle.
  • POST /region-lifecycles/{lifecycle_id}/constraints — Confirm refinement constraints.
  • POST /region-lifecycles/{lifecycle_id}/proposal-set — Build and rank a proposal set.
  • POST /region-lifecycles/{lifecycle_id}/compile-recipe — Compile constraints into a selection recipe.
  • POST /region-lifecycles/{lifecycle_id}/generate — Generate candidate proposals (owner-only; fails closed when the proprietary engine is absent).
  • POST /region-lifecycles/{lifecycle_id}/select — Select one candidate proposal.
  • POST /region-lifecycles/{lifecycle_id}/approve — Approve the selected proposal (human gate).
  • POST /region-lifecycles/{lifecycle_id}/attestation/retry — Retry signing the approval attestation.
  • POST /region-lifecycles/{lifecycle_id}/review — Hand off the approved region to candidate review.
  • GET /region-lifecycles/{lifecycle_id} — Read lifecycle state and digests.
  • GET /region-lifecycles/{lifecycle_id}/proposal-set — Rehydrate the attached proposal set.
  • GET /region-lifecycles/{lifecycle_id}/approved-region — Rehydrate the approved region.

Example requests

Request field names are taken verbatim from the schemas in apps/backend/openapi.json — one example per router. Values below are illustrative, not live data.

Public — POST /upload/token (TokenRequest)

{
  "contentUid": "sha256-v1:2f9c1b8a...",
  "rawSha256": "8a4e6d51...",
  "sizeBytes": 5744640,
  "filename": "WNAT_Hagen.14"
}

Maintainer (contribution review) — POST /approve (ApproveRequest)

{
  "jobId": "job_9f3a2c1d"
}

Maintainer (region lifecycle) — POST /region-lifecycles/{lifecycle_id}/approve (ApproveReq)

{
  "proposal_set": { "...": "the proposal-set-v1 document" },
  "proposal_id": "p1",
  "reason": "meets confirmed constraints",
  "allowed_classes": ["geometry"],
  "immutable_classes": ["boundary"],
  "magnitude_bounds": { "geometry": 5.0 },
  "name": "hagen-refine-1"
}

The response bodies for these routes are not modeled as typed OpenAPI schemas (they return plain JSON objects), so no response shape is asserted here — see the field names each route's handler returns directly in apps/backend/api/.

OpenAPI

The committed schema lives at apps/backend/openapi.json. The backend service exposes Swagger UI at `https://<backend-host>/docs`, ReDoc at `https://<backend-host>/redoc`, and the schema at `https://<backend-host>/openapi.json`.