Competencies API

Competencies are installable capability bundles (system prompt + required skills + settings schema) that get equipped onto agents, in operator-controlled order.

There is no POST /competencies/{id}/equip or POST /competencies/{id}/unequip endpoint. Equip state is read via GET /agents/{id}/competencies and reordered via PUT /agents/{id}/competencies/order; a competency is realised onto an agent as a side effect of installing/upgrading the agent package (see using-competencies.md and catalog.md), not through a direct equip/unequip call.

Endpoints

There is no POST /competencies/{id}/deps/install, /pause, /resume, /deactivate, or /activate. Competencies don't have an independent activate/pause/resume lifecycle — they're realised into an agent at install/upgrade time (ADR-044), and a missing skill dependency is installed directly, not through a deps/install call. See using-competencies.md.

GET /competencies/active always returns [] — its HozironPlatform implementation (list_active_competencies()) does not reflect what's actually equipped to running agents. GET/PUT /competencies/{id}/config (the non-agent-scoped form) both return 410 Gone pointing at the agent-scoped replacement below.

GET /competencies

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/competencies

Response (200) — CompetencyInfo[]

{
  "competencies": [
    {
      "id": "claims-intake",
      "name": "Claims Intake",
      "version": "1.2.0",
      "status": "Installed",
      "skills": ["document-ocr", "postgresql-connector"]
    }
  ]
}

status is "Installed", "Equipped", or {"Error": "<message>"}.

POST /competencies/install

curl -X POST -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"path": "/opt/hoziron/packages/claims-intake"}' \
  http://localhost:4200/competencies/install

Response (201)

{"id": "claims-intake"}

GET /competencies/{id}

Response (200) — CompetencyDetail

{
  "id": "claims-intake",
  "manifest": {
    "id": "claims-intake",
    "name": "Claims Intake",
    "version": "1.2.0",
    "description": "First Notice of Loss processing",
    "system_prompt": "You are a claims intake specialist...",
    "skills": ["document-ocr", "postgresql-connector"],
    "permissions": [],
    "settings": [],
    "schedule": null
  },
  "status": "Installed",
  "skill_states": [
    {"skill_id": "document-ocr", "state": "Installed"},
    {"skill_id": "postgresql-connector", "state": "Missing"}
  ]
}

GET /competencies/{id}/validate-deps (alias: /competencies/{id}/deps)

Response (200) — DependencyReport

{
  "competency_id": "claims-intake",
  "skills": [
    {"skill_id": "document-ocr", "state": "Installed"},
    {"skill_id": "postgresql-connector", "state": "Missing"}
  ],
  "ready": false
}

GET /agents/{id}/competencies

{"competencies": ["claims-intake", "escalation-routing"]}

Order reflects equip order — the system prompts are concatenated in this order when the agent runs.

PUT /agents/{id}/competencies/order

curl -X PUT -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"order": ["escalation-routing", "claims-intake"]}' \
  http://localhost:4200/agents/550e8400-e29b-41d4-a716-446655440000/competencies/order

Response (200)

Empty body.

GET /agents/{id}/competencies/{cid}/config · PUT .../config

Agent-scoped competency configuration — the supported alternative to the non-agent-scoped /competencies/{id}/config below.

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/agents/550e8400-.../competencies/claims-intake/config

curl -X PUT -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"auto_escalate_threshold": "5000"}' \
  http://localhost:4200/agents/550e8400-.../competencies/claims-intake/config

GET returns the current config values plus the settings schema (so a UI can render a form); PUT returns {"status": "updated"}.

GET /competencies/schedule-health

Detects drift between an equipped competency's manifest-declared schedule and the actual cron binding.

{"drift": []}

POST /agents/{agent_id}/competencies/{cid}/reset-schedule

{"status": "reset"}

GET/PUT /competencies/{id}/config (non-agent-scoped)

Both return 410 Gone:

{
  "deprecated": true,
  "message": "This endpoint is deprecated. Use GET /agents/{agent_id}/competencies/{cid}/config instead.",
  "values": {},
  "schema": []
}

Related

• agents.md — equipping competencies onto an agent
• skills.md — the skill dependencies a competency declares
• catalog.md — installing competency packages from a registry