Skip to content
Claresia Docs

Skill entitlement API

The Skill Entitlement API governs who sees which skills in their LLM picker. Backed by the cc-061 archetype assignment + per-group augments + per-skill RBAC blocklists.

Endpoint

Section titled “Endpoint”
https://api.claresia.com/api/v1/skill-entitlement

Get effective entitlement for a user

Section titled “Get effective entitlement for a user”
GET /api/v1/skill-entitlement/users/user:marco.mazzolin@dainese.it

Response:

{
  "user_id": "user:marco.mazzolin@dainese.it",
  "archetype_id": "firmware_engineer",
  "effective_skills": [
    { "skill_id": "gatespic.incident-postmortem", "skill_version": "1.4.2",
      "source": "archetype:firmware_engineer", "granted_at": "2026-04-25T10:00:00Z" },
    { "skill_id": "gatespic.firmware-changelog-qa", "skill_version": "1.0.4",
      "source": "archetype:firmware_engineer", "granted_at": "2026-04-25T10:00:00Z" },
    { "skill_id": "steve.prd-review", "skill_version": "1.2.0",
      "source": "group:claresia-eng-pilot", "granted_at": "2026-04-25T10:00:00Z" },
    { "skill_id": "boss.standup-notes", "skill_version": "1.1.0",
      "source": "user_grant", "granted_at": "2026-05-01T09:00:00Z" }
  ],
  "blocked_skills": [
    { "skill_id": "clawshield.deal-desk", "blocked_by": "group:claresia-restricted-no-pii" }
  ]
}

Get archetype-level grants

Section titled “Get archetype-level grants”
GET /api/v1/skill-entitlement/archetypes/firmware_engineer

Response:

{
  "archetype_id": "firmware_engineer",
  "cowork_id": "firmware-engineer.dainese.v1",
  "skills": [
    { "skill_id": "gatespic.incident-postmortem", "skill_version": "1.4.2", "source": "cowork" },
    { "skill_id": "gatespic.firmware-changelog-qa", "skill_version": "1.0.4", "source": "cowork" },
    { "skill_id": "gatespic.change-risk-review", "skill_version": "1.1.1", "source": "cowork" },
    { "skill_id": "gatespic.security-advisory-triage", "skill_version": "1.0.2", "source": "cowork" },
    { "skill_id": "gatespic.runbook-suggest", "skill_version": "1.0.6", "source": "cowork" }
  ],
  "user_count": 42
}

Modify archetype-level grants

Section titled “Modify archetype-level grants”
PATCH /api/v1/skill-entitlement/archetypes/firmware_engineer
Content-Type: application/json


{
  "add_skills": ["steve.prd-review"],
  "remove_skills": ["gatespic.security-advisory-triage"]
}

Response:

{
  "archetype_id": "firmware_engineer",
  "added": ["steve.prd-review"],
  "removed": ["gatespic.security-advisory-triage"],
  "publish_lag_estimate_seconds": 45,
  "publish_job_id": "pub_2H8j4..."
}

A governance_event of kind skill.entitlement_changed is auto-emitted.

The Distribution Plane is triggered to re-publish — the SLO is <60s p99 for the change to appear in end-user LLM pickers.

Add a group-level augment

Section titled “Add a group-level augment”
POST /api/v1/skill-entitlement/groups/claresia-eng-pilot/augment
Content-Type: application/json


{
  "additive_skills": ["steve.prd-review", "boss.team-weekly-digest"]
}

The augment is additive to the user’s archetype defaults. Useful for “pilot cohort gets more skills than the rest of the archetype.”

Block a skill for a group

Section titled “Block a skill for a group”
POST /api/v1/skill-entitlement/groups/claresia-restricted-no-pii/block
Content-Type: application/json


{
  "blocked_skills": ["clawshield.deal-desk", "ledger.vendor-spend-review"]
}

Blocks override grants — even if the archetype has the skill, members of the blocked group won’t see it.

User-level grant (rare; use sparingly)

Section titled “User-level grant (rare; use sparingly)”
POST /api/v1/skill-entitlement/users/user:marco.mazzolin@dainese.it/grant
Content-Type: application/json


{
  "skill_id": "boss.standup-notes",
  "reason": "Acting eng lead for Q2 — temporary grant"
}

User-level grants should be time-bounded — set expires_at:

{
  "skill_id": "boss.standup-notes",
  "expires_at": "2026-08-01T00:00:00Z",
  "reason": "Acting eng lead for Q2"
}

After expiry the grant is auto-revoked + a governance_event emitted.

Trigger a manual re-publish

Section titled “Trigger a manual re-publish”
POST /api/v1/skill-entitlement/distribution:republish
Content-Type: application/json


{
  "scope": "tenant",
  "platforms": ["anthropic-claude-enterprise", "microsoft-copilot-m365"]
}

Useful if you suspect a stale publish (e.g., end users not seeing the latest toggles).

Response:

{
  "publish_jobs": [
    { "platform": "anthropic-claude-enterprise", "job_id": "pub_2H8j4...", "status": "queued" },
    { "platform": "microsoft-copilot-m365", "job_id": "pub_3J9k5...", "status": "queued" }
  ]
}

Poll job:

GET /api/v1/skill-entitlement/distribution/jobs/pub_2H8j4...

Cowork apply (one-shot)

Section titled “Cowork apply (one-shot)”

Apply a Cowork to all users of an archetype:

POST /api/v1/skill-entitlement/coworks/firmware-engineer.dainese.v1:apply
Content-Type: application/json


{
  "scope_archetypes": ["firmware_engineer"],
  "merge_mode": "replace_archetype_default"
}

merge_mode options:

  • replace_archetype_default — overwrite archetype’s skill list with the Cowork’s
  • merge — add Cowork’s skills to existing list (no removal)
  • additive_only_for_pilot_group — apply only to members of the named group

Errors

Section titled “Errors”
HTTPMeaning
400Invalid skill_id (not in catalog) or archetype_id
403Need skill_entitlement:write scope
422Skill is in lifecycle.state=draft (cannot grant) or deprecated (warning)
423Locked by an active publish job; retry in 60s

Reference

Section titled “Reference”