Roster API

The Roster API exposes the per-tenant user roster, archetype assignments, and group memberships. The roster is auto-populated from your IdP via SCIM; the API lets you read it, override archetypes, and integrate downstream systems (HRIS, CRM, BI).

Endpoint

https://api.claresia.com/api/v1/roster

List users

GET /api/v1/roster/users?archetype=firmware_engineer&active=true&limit=100
Authorization: Bearer <jwt>
X-Claresia-Tenant: dainese

Response:

{
  "users": [
    {
      "user_id": "user:marco.mazzolin@dainese.it",
      "email": "marco.mazzolin@dainese.it",
      "first_name": "Marco",
      "last_name": "Mazzolin",
      "job_title": "Firmware Engineer",
      "department": "R&D",
      "manager_user_id": "user:luigi.bianchi@dainese.it",
      "archetype_id": "firmware_engineer",
      "archetype_confidence": 0.992,
      "archetype_assigned_by": "service:cc-061-classifier",
      "archetype_assigned_at": "2026-04-25T10:00:00Z",
      "is_active": true,
      "scim_external_id": "5f8d3a2b-...",
      "groups": ["claresia-users", "claresia-eng-pilot"]
    }
  ],
  "next_cursor": "..."
}

Query parameters

Param	Type	Notes
archetype	string	Filter by archetype
active	bool	Default true
email	string	Exact-match lookup
manager_user_id	string	List a manager’s direct reports
department	string
group	string	Filter by group membership
archetype_confidence__lt	float	Find low-confidence assignments for review

Get a single user

GET /api/v1/roster/users/user:marco.mazzolin@dainese.it

Override archetype

PATCH /api/v1/roster/users/user:marco.mazzolin@dainese.it
Content-Type: application/json

{
  "archetype_id": "eng_lead"
}

Response:

{
  "user_id": "user:marco.mazzolin@dainese.it",
  "archetype_id": "eng_lead",
  "archetype_confidence": 1.0,
  "archetype_assigned_by": "user:it.admin@dainese.it",
  "archetype_assigned_at": "2026-05-03T14:30:00Z"
}

A governance_event of kind rbac.archetype_overridden is auto-emitted.

After change, the Distribution Plane re-publishes within 60s to update the user’s skill picker in their LLM.

Bulk archetype assignment

POST /api/v1/roster/archetype:bulk-assign
Content-Type: application/json

{
  "assignments": [
    { "user_id": "user:alice@dainese.it", "archetype_id": "fpa_analyst" },
    { "user_id": "user:bob@dainese.it", "archetype_id": "production_planner" }
  ]
}

Response:

{
  "updated": 2,
  "failed": 0,
  "errors": []
}

List archetypes

GET /api/v1/roster/archetypes

Response:

{
  "archetypes": [
    {
      "archetype_id": "firmware_engineer",
      "title": "Firmware Engineer",
      "function_focus": ["gatespic", "steve"],
      "default_cowork_id": "firmware-engineer.dainese.v1",
      "user_count": 42,
      "active_user_count": 41
    },
    ...
  ]
}

List groups

GET /api/v1/roster/groups

Response:

{
  "groups": [
    {
      "group_id": "claresia-eng-pilot",
      "display_name": "Engineering Pilot",
      "source": "scim:azure-ad",
      "member_count": 12,
      "claresia_role": "member"
    },
    ...
  ]
}

Force a SCIM re-sync

POST /api/v1/roster/scim:sync

Response:

{
  "job_id": "scim-sync-2H8j4...",
  "status": "queued",
  "started_at": "2026-05-03T14:32:00Z"
}

Poll:

GET /api/v1/roster/scim/jobs/scim-sync-2H8j4...

Archetype confidence + manual review

The cc-061 classifier returns a confidence per assignment. Confidence < 0.7 is flagged for manual review. List unmatched / low-confidence:

GET /api/v1/roster/users?archetype_confidence__lt=0.7

Use this to clean up edge-case titles in your roster (e.g., “Sr. Mfg. Director of EMEA” — likely a director-level production_planner).

CSV export

GET /api/v1/roster/users:export?format=csv

Returns:

user_id,email,first_name,last_name,job_title,department,manager,archetype_id,archetype_confidence,is_active,groups
user:marco.mazzolin@dainese.it,marco.mazzolin@dainese.it,Marco,Mazzolin,Firmware Engineer,R&D,luigi.bianchi@dainese.it,firmware_engineer,0.992,true,"claresia-users,claresia-eng-pilot"
...

Webhook events (subscribe via Settings)

• roster.user_created
• roster.user_updated
• roster.user_deactivated
• roster.archetype_assigned
• roster.archetype_overridden

Errors

HTTP	Meaning
400	Invalid archetype_id (not in cc-051 bundle for this tenant)
403	Need roster:write scope
404	User not found
409	SCIM sync in progress (concurrent override)
422	Manual override blocked by tenant policy