Delete Facility

Delete a facility and its whole subtree from your organization's view.

This is a visibility delete, not a data delete. It removes the facility โ€” and, by cascade, all of its supply sheds and all of their plots โ€” from your organization: they stop appearing in GET /locations/* and their metrics disappear from /metrics/* (and /metrics/{type}/:id/{metric} returns 404). The underlying geometry, assessments, and metric history are preserved, so the location revives automatically if you re-upload a matching location later. Locations shared with other organizations are unaffected โ€” only your organization's view changes.

Cascade

Deletion cascades downward only (an asset and its descendants, never a parent):

You delete aโ€ฆRemoved
FacilityThe facility + all its sheds + all their plots
ShedThe shed + its plots (parent facility and sibling sheds untouched)
PlotThat plot only

Request

Method & Path

DELETE /locations/facilities/:id

:id is the location's public id (the same id returned by GET /locations/:id).

Query parameters

  • detach_from_pending_dds (boolean, default true) โ€” controls how a plot in the cascade that is pinned by a pending (unfrozen) DDS version is handled:

    • true (default) โ€” detach the plot from the pending version (removing its pin and any draft exclusion/justification) and proceed with the delete.
    • false โ€” do not touch DDS; if any cascade plot is pinned by a pending version, the delete is rejected with 409 and the blocking version ids are returned in details.pending_dds_version_ids.

    A frozen DDS version (submitted, in-flight, or frozen by a version cut) is never modified โ€” its filing keeps rendering โ€” regardless of this flag.

Response

  • 204 No Content โ€” deleted (no body).
  • 403 โ€” the key lacks the locations:delete scope.
  • 404 โ€” no facility with that id is visible to your organization. (A parent organization must use x-acting-as to delete a child org's location.)
  • 409 CONFLICT โ€” detach_from_pending_dds=false and a cascade plot is pinned by a pending DDS version; see details.pending_dds_version_ids.

See error-codes.md for the shared error envelope.

Required scope: locations:delete