Hierarchy Cache - API Contract

GET /api/v1/hierarchy-cache/api/v1/hierarchy-cache

List all cached hierarchy entries

Public

Response Example

{
  "data": [
    {
      "cache_key": "hierarchy:org-42",
      "organization_id": "org-42",
      "cached_at": "2026-03-26T09:00:00Z",
      "expires_at": "2026-03-26T10:00:00Z",
      "node_count": 12
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3
  }
}

GET /api/v1/hierarchy-cache/api/v1/hierarchy-cache/{organizationId}

Get the cached hierarchy tree for an organization

Public

Response Example

{
  "organization_id": "org-42",
  "cached_at": "2026-03-26T09:00:00Z",
  "expires_at": "2026-03-26T10:00:00Z",
  "tree": [
    {
      "unit_id": "unit-001",
      "name": "Northern Region",
      "level_type": "region",
      "parent_id": null,
      "children": [
        {
          "unit_id": "unit-002",
          "name": "Oslo Chapter",
          "level_type": "chapter",
          "parent_id": "unit-001",
          "children": []
        }
      ]
    }
  ]
}

POST /api/v1/hierarchy-cache/api/v1/hierarchy-cache

Populate the cache for an organization's hierarchy tree

Public

Request Example

{
  "organization_id": "org-42",
  "tree": [
    {
      "unit_id": "unit-001",
      "name": "Northern Region",
      "level_type": "region",
      "parent_id": null,
      "children": []
    }
  ]
}

Response Example

{
  "organization_id": "org-42",
  "cached_at": "2026-03-26T10:00:00Z",
  "expires_at": "2026-03-26T11:00:00Z"
}

PUT /api/v1/hierarchy-cache/api/v1/hierarchy-cache/{organizationId}

Replace/refresh the cached tree for an organization

Public

Request Example

{
  "tree": [
    {
      "unit_id": "unit-001",
      "name": "Northern Region",
      "level_type": "region",
      "parent_id": null,
      "children": [
        {
          "unit_id": "unit-019",
          "name": "Bergen Chapter",
          "level_type": "chapter",
          "parent_id": "unit-001",
          "children": []
        }
      ]
    }
  ]
}

Response Example

{
  "organization_id": "org-42",
  "updated_at": "2026-03-26T11:05:00Z",
  "expires_at": "2026-03-26T12:05:00Z"
}

DELETE /api/v1/hierarchy-cache/api/v1/hierarchy-cache/{organizationId}

Invalidate the full hierarchy cache for an organization

Public

Response Example

{
  "invalidated": true,
  "organization_id": "org-42"
}

DELETE /api/v1/hierarchy-cache/api/v1/hierarchy-cache/{organizationId}/nodes/{unitId}

Invalidate a single node in the cached hierarchy

Public

Response Example

{
  "invalidated": true,
  "organization_id": "org-42",
  "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"
}