Hierarchy Service - API Contract

GET /api/v1/organizations/{organizationId}/units/api/v1/organizations/{organizationId}/units

Get full hierarchy tree for an organization

Public

Response Example

{
  "data": [
    {
      "unit_id": "unit-001",
      "organization_id": "org-42",
      "name": "Northern Region",
      "level_type": "region",
      "parent_id": null,
      "depth": 0,
      "children_count": 4,
      "created_at": "2025-01-15T09:00:00Z"
    },
    {
      "unit_id": "unit-002",
      "organization_id": "org-42",
      "name": "Oslo Chapter",
      "level_type": "chapter",
      "parent_id": "unit-001",
      "depth": 1,
      "children_count": 0,
      "created_at": "2025-02-10T11:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12
  }
}

GET /api/v1/organizations/{organizationId}/units/api/v1/organizations/{organizationId}/units/{unitId}

Get a single unit by ID

Public

Response Example

{
  "unit_id": "unit-002",
  "organization_id": "org-42",
  "name": "Oslo Chapter",
  "level_type": "chapter",
  "parent_id": "unit-001",
  "depth": 1,
  "ancestors": [
    {
      "unit_id": "unit-001",
      "name": "Northern Region",
      "level_type": "region"
    }
  ],
  "children_count": 0,
  "created_at": "2025-02-10T11:30:00Z",
  "updated_at": "2025-03-01T08:00:00Z"
}

POST /api/v1/organizations/{organizationId}/units/api/v1/organizations/{organizationId}/units

Create a new organizational unit

Public

Request Example

{
  "name": "Bergen Chapter",
  "level_type": "chapter",
  "parent_id": "unit-001"
}

Response Example

{
  "unit_id": "unit-019",
  "organization_id": "org-42",
  "name": "Bergen Chapter",
  "level_type": "chapter",
  "parent_id": "unit-001",
  "depth": 1,
  "children_count": 0,
  "created_at": "2026-03-26T10:15:00Z"
}

PUT /api/v1/organizations/{organizationId}/units/api/v1/organizations/{organizationId}/units/{unitId}

Update an existing unit (rename, reparent, change level)

Public

Request Example

{
  "name": "Bergen & Surrounds Chapter",
  "parent_id": "unit-003"
}

Response Example

{
  "unit_id": "unit-019",
  "organization_id": "org-42",
  "name": "Bergen & Surrounds Chapter",
  "level_type": "chapter",
  "parent_id": "unit-003",
  "depth": 1,
  "updated_at": "2026-03-26T14:00:00Z"
}

DELETE /api/v1/organizations/{organizationId}/units/api/v1/organizations/{organizationId}/units/{unitId}

Delete a unit (validates orphan-free before deletion)

Public

Response Example

{
  "deleted": true,
  "unit_id": "unit-019"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}