Skills

GET /api/orgs/{org_id}/skills

List Skills

List skills in the organization.

Omit limit to get every skill; total is the full count either way.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no	Max rows to return (1-100). Omit to return every row.
offset	query	integer	no	Rows to skip — pass the previous response’s next_offset.
org_id	path	string (uuid)	yes
project_id	query	string	no	Filter by project id, or ‘none’ for uncategorized skills.

Responses

Status	Description	Body
200	Successful Response	Page_SkillResponse_
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/skills

Create Skill

Create a new skill. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
description	string	no
instructions	string	yes
name	string	yes
reference_material	string	no
slug	string	no
tool_slugs	string[]	no

Responses

Status	Description	Body
201	Successful Response	SkillResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/skills/{id_or_slug}

Get Skill

Get a skill by ID or slug, including active and draft revisions.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	SkillResponse
422	Validation Error	HTTPValidationError

PUT /api/orgs/{org_id}/skills/{skill_id}

Update Skill

Update a skill. name/description update the parent; instructions/tool_slugs/reference_material go to a draft revision. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
skill_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
description	string	no
instructions	string	no
name	string	no
reference_material	string	no
tool_slugs	string[]	no

Responses

Status	Description	Body
200	Successful Response	SkillResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/skills/{skill_id}

Delete Skill

Soft-delete a skill. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
skill_id	path	string (uuid)	yes

Responses

Status	Description	Body
204	Successful Response
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/skills/{skill_id}/deploy

Deploy Skill

Promote the draft revision to active. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
skill_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	SkillResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/skills/{skill_id}/draft

Discard Skill Draft

Discard the draft revision for a skill. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
skill_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	SkillResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/skills/{skill_id}/revisions

List Skill Revisions

List all revisions for a skill, newest first.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
skill_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	SkillRevisionResponse[]
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/skills/{skill_id}/usage

Get Skill Usage

List activation records for a skill, newest first.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no
org_id	path	string (uuid)	yes
skill_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	SkillActivationRecordResponse[]
422	Validation Error	HTTPValidationError