Label Key Resolver - API Contract

GET /api/v1/label-key-resolutions/api/v1/label-key-resolutions

List all known resolvable label keys with their current resolved values for an organization

Auth Required coordinatororg_adminglobal_admin

Response Example

{
  "data": [
    {
      "key": "role.coordinator",
      "resolved_value": "Programleder",
      "fallback_value": "Coordinator",
      "has_custom_override": true
    },
    {
      "key": "role.peer_mentor",
      "resolved_value": "Peer Mentor",
      "fallback_value": "Peer Mentor",
      "has_custom_override": false
    },
    {
      "key": "activity_type.café_visit",
      "resolved_value": "Kafé-besøk",
      "fallback_value": "Café Visit",
      "has_custom_override": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 31
  }
}

GET /api/v1/label-key-resolutions/api/v1/label-key-resolutions/:key

Get resolution details for a specific label key

Auth Required peer_mentorcoordinatororg_adminglobal_admin

Response Example

{
  "key": "role.coordinator",
  "resolved_value": "Programleder",
  "fallback_value": "Coordinator",
  "has_custom_override": true,
  "valid_convention": true
}

POST /api/v1/label-key-resolutions/api/v1/label-key-resolutions

Create a resolution record for a new label key

Auth Required org_adminglobal_admin

Request Example

{
  "key": "report.engagement_score",
  "default_value": "Engagement Score",
  "organization_id": "org_nhf_oslo",
  "params": {
    "unit": "%"
  }
}

Response Example

{
  "key": "report.engagement_score",
  "resolved_value": "Engagement Score",
  "valid_convention": true,
  "created_at": "2026-03-26T09:30:00.000Z"
}

PUT /api/v1/label-key-resolutions/api/v1/label-key-resolutions/:key

Update the default or override value for a label key resolution

Auth Required org_adminglobal_admin

Request Example

{
  "default_value": "Engagement Rate",
  "params": {
    "unit": "%"
  }
}

Response Example

{
  "key": "report.engagement_score",
  "resolved_value": "Engagement Rate",
  "updated_at": "2026-03-26T09:35:00.000Z"
}

DELETE /api/v1/label-key-resolutions/api/v1/label-key-resolutions/:key

Remove a label key resolution record

Auth Required global_admin

Response Example

{
  "key": "report.engagement_score",
  "deleted": true
}

POST /api/v1/label-key-resolutions/api/v1/label-key-resolutions/resolve

Resolve a label key against a provided map with optional interpolation params (maps to resolve())

Auth Required peer_mentorcoordinatororg_adminglobal_admin

Request Example

{
  "key": "activity_type.group_walk",
  "organization_id": "org_nhf_oslo",
  "params": {
    "count": 5
  }
}

Response Example

{
  "key": "activity_type.group_walk",
  "resolved_value": "Fellestur (5)",
  "source": "organization_override"
}

POST /api/v1/label-key-resolutions/api/v1/label-key-resolutions/resolve-with-fallback

Resolve a label key with an explicit client-supplied fallback string (maps to resolveWithFallback())

Auth Required peer_mentorcoordinatororg_adminglobal_admin

Request Example

{
  "key": "activity_type.unknown_type",
  "organization_id": "org_hlf",
  "fallback": "Custom Activity"
}

Response Example

{
  "key": "activity_type.unknown_type",
  "resolved_value": "Custom Activity",
  "source": "fallback"
}

POST /api/v1/label-key-resolutions/api/v1/label-key-resolutions/validate-key

Check whether a label key string conforms to naming conventions (maps to validateKeyConvention())

Auth Required coordinatororg_adminglobal_admin

Request Example

{
  "key": "role.peer_mentor"
}

Response Example

{
  "key": "role.peer_mentor",
  "valid": true,
  "issues": []
}

GET /api/v1/label-key-resolutions/api/v1/label-key-resolutions/default-fallback-map

Retrieve the system-wide default fallback label map (maps to buildDefaultFallbackMap())

Auth Required coordinatororg_adminglobal_admin

Response Example

{
  "fallback_map": {
    "role.coordinator": "Coordinator",
    "role.peer_mentor": "Peer Mentor",
    "activity_type.group_walk": "Group Walk",
    "activity_type.café_visit": "Café Visit",
    "activity_type.home_visit": "Home Visit",
    "report.participant_count": "Participant Count",
    "report.session_duration": "Session Duration"
  },
  "total_keys": 24
}

Additional Metadata

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