Multi-Org Membership Resolver - API Contract

GET /api/v1/memberships/api/v1/memberships

List all memberships (filterable by user_id or org_id)

Public

Response Example

{
  "data": [
    {
      "membership_id": "mem_01J4K8P3N7Q2R5S8",
      "user_id": "usr_01J4K8M2N3P5Q7A1",
      "org_id": "org_01J4K8M2N3P5Q7R9",
      "org_name": "Northbrook Academy",
      "role": "admin",
      "is_primary": true,
      "joined_at": "2024-03-15T08:00:00Z"
    },
    {
      "membership_id": "mem_01J4K8P3N7Q2R5S9",
      "user_id": "usr_01J4K8M2N3P5Q7A1",
      "org_id": "org_01J4K8M2N3P5Q7R8",
      "org_name": "Westfield Learning Hub",
      "role": "member",
      "is_primary": false,
      "joined_at": "2025-01-10T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/memberships/api/v1/memberships/:id

Get a single membership record by membership ID

Public

Response Example

{
  "membership_id": "mem_01J4K8P3N7Q2R5S8",
  "user_id": "usr_01J4K8M2N3P5Q7A1",
  "org_id": "org_01J4K8M2N3P5Q7R9",
  "org_name": "Northbrook Academy",
  "role": "admin",
  "is_primary": true,
  "joined_at": "2024-03-15T08:00:00Z"
}

POST /api/v1/memberships/api/v1/memberships

Add a user to an organization

Public

Request Example

{
  "user_id": "usr_01J9X3P7K2M4N6B2",
  "org_id": "org_01J4K8M2N3P5Q7R9",
  "role": "member",
  "is_primary": false
}

Response Example

{
  "membership_id": "mem_01J9X3P7K2M4N6C3",
  "user_id": "usr_01J9X3P7K2M4N6B2",
  "org_id": "org_01J4K8M2N3P5Q7R9",
  "org_name": "Northbrook Academy",
  "role": "member",
  "is_primary": false,
  "joined_at": "2026-03-26T12:00:00Z",
  "created_at": "2026-03-26T12:00:00Z"
}

PUT /api/v1/memberships/api/v1/memberships/:id

Update membership role or primary flag

Public

Request Example

{
  "role": "admin",
  "is_primary": true
}

Response Example

{
  "membership_id": "mem_01J9X3P7K2M4N6C3",
  "user_id": "usr_01J9X3P7K2M4N6B2",
  "org_id": "org_01J4K8M2N3P5Q7R9",
  "org_name": "Northbrook Academy",
  "role": "admin",
  "is_primary": true,
  "joined_at": "2026-03-26T12:00:00Z",
  "updated_at": "2026-03-26T14:00:00Z"
}

DELETE /api/v1/memberships/api/v1/memberships/:id

Remove a user from an organization

Public

Response Example

{
  "success": true,
  "removed_at": "2026-03-26T15:00:00Z"
}

GET /api/v1/memberships/api/v1/memberships/users/:userId/organizations

Get all organizations a user belongs to, with primary org first

Public

Response Example

{
  "user_id": "usr_01J4K8M2N3P5Q7A1",
  "has_multiple_organizations": true,
  "primary_org": {
    "org_id": "org_01J4K8M2N3P5Q7R9",
    "name": "Northbrook Academy",
    "role": "admin"
  },
  "organizations": [
    {
      "org_id": "org_01J4K8M2N3P5Q7R9",
      "name": "Northbrook Academy",
      "role": "admin",
      "is_primary": true
    },
    {
      "org_id": "org_01J4K8M2N3P5Q7R8",
      "name": "Westfield Learning Hub",
      "role": "member",
      "is_primary": false
    }
  ]
}

Additional Metadata

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