Org Hierarchy Service - API Contract

GET /api/v1/orgs/api/v1/orgs

List orgs (paginated)

Public

Response Example

{
  "data": [
    {
      "org_id": "org_kNr8aQ",
      "name": "Stavanger Region",
      "parent_org_id": null,
      "level": 0
    },
    {
      "org_id": "org_tY2zLm",
      "name": "Rogaland Nord",
      "parent_org_id": "org_kNr8aQ",
      "level": 1
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 6
  }
}

GET /api/v1/orgs/api/v1/orgs/:id

Get a single org node

Public

Response Example

{
  "data": {
    "org_id": "org_kNr8aQ",
    "name": "Stavanger Region",
    "parent_org_id": null,
    "level": 0,
    "created_at": "2024-01-10T00:00:00Z"
  }
}

POST /api/v1/orgs/api/v1/orgs

Create a new org node

Public

Request Example

{
  "name": "Haugaland Sør",
  "parent_org_id": "org_kNr8aQ"
}

Response Example

{
  "data": {
    "org_id": "org_xW7pNq",
    "name": "Haugaland Sør",
    "parent_org_id": "org_kNr8aQ",
    "level": 1,
    "created_at": "2026-03-26T11:00:00Z"
  }
}

PUT /api/v1/orgs/api/v1/orgs/:id

Update an org node

Public

Request Example

{
  "name": "Haugaland Sør og Vest"
}

Response Example

{
  "data": {
    "org_id": "org_xW7pNq",
    "name": "Haugaland Sør og Vest",
    "parent_org_id": "org_kNr8aQ",
    "level": 1,
    "updated_at": "2026-03-26T13:00:00Z"
  }
}

DELETE /api/v1/orgs/api/v1/orgs/:id

Remove an org node (only if no children)

Public

Response Example

{
  "data": {
    "org_id": "org_xW7pNq",
    "deleted": true
  }
}

GET /api/v1/orgs/api/v1/orgs/tree

Get full org tree from a root

Public

Response Example

{
  "data": {
    "org_id": "org_kNr8aQ",
    "name": "Stavanger Region",
    "level": 0,
    "children": [
      {
        "org_id": "org_tY2zLm",
        "name": "Rogaland Nord",
        "level": 1,
        "children": []
      }
    ]
  }
}

GET /api/v1/orgs/api/v1/orgs/:id/descendants

Get all descendant org IDs

Public

Response Example

{
  "data": {
    "org_id": "org_kNr8aQ",
    "descendant_ids": [
      "org_tY2zLm",
      "org_xW7pNq",
      "org_mP4cBv"
    ]
  }
}

GET /api/v1/orgs/api/v1/orgs/:id/ancestors

Get ancestor path from root to this org

Public

Response Example

{
  "data": {
    "org_id": "org_mP4cBv",
    "ancestors": [
      {
        "org_id": "org_kNr8aQ",
        "name": "Stavanger Region",
        "level": 0
      },
      {
        "org_id": "org_tY2zLm",
        "name": "Rogaland Nord",
        "level": 1
      }
    ]
  }
}

GET /api/v1/orgs/api/v1/orgs/search

Search org nodes by name within a subtree

Public

Response Example

{
  "data": [
    {
      "org_id": "org_tY2zLm",
      "name": "Rogaland Nord",
      "level": 1,
      "parent_org_id": "org_kNr8aQ"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

Additional Metadata

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