Manage Workspace Skills with the REST API
List, read, create, update, and delete skills that are available to one workspace, and reference a skill in a pipeline.
About This Task
Skills have a source that tells you where they are available:
DEEPSET: Skills built by deepset. They are available to everyone and are read-only.ORG: Skills from your organization's skills repository. They are available in all workspaces.WORKSPACE: Skills that you scoped to one workspace in the Available to setting of the Skills page.
The endpoints under /api/v2/skills work on the organization's catalog. That catalog holds DEEPSET and ORG skills only, so GET /api/v2/skills doesn't list WORKSPACE skills. The endpoints that take a skill ID under /api/v2/skills don't know which workspace to look in. If you set source=WORKSPACE on them, they return a 400 error that says a workspace-scoped skill requires a workspace ID.
To work with WORKSPACE skills, use the endpoints under /api/v2/workspaces/{workspace_id}/skills. The workspace ID is part of the path, and these endpoints list the skills of all three sources that you can use in that workspace.
These endpoints check your permissions for skills in the workspace. You need read permission to list and get skills, write permission to create and update them, and permission to delete skills to delete them. The organization endpoints under /api/v2/skills need an organization role instead.
Prerequisites
- An API Key to connect to Haystack Enterprise Platform.
- The ID of the workspace. For details, see Workspace ID.
Endpoints
All paths start with https://api.cloud.deepset.ai.
| Task | Method and path |
|---|---|
| List the skills you can use in the workspace | GET /api/v2/workspaces/{workspace_id}/skills |
| Get a skill | GET /api/v2/workspaces/{workspace_id}/skills/{skill_id} |
| List the versions of a skill | GET /api/v2/workspaces/{workspace_id}/skills/{skill_id}/history |
| Create a workspace skill | POST /api/v2/workspaces/{workspace_id}/skills |
| Update a workspace skill | PUT /api/v2/workspaces/{workspace_id}/skills/{skill_id} |
| Delete a workspace skill | DELETE /api/v2/workspaces/{workspace_id}/skills/{skill_id} |
List and Get Skills
- List the skills. The response includes the skills of the
DEEPSET,ORG, andWORKSPACEsources. Skills with the sourceWORKSPACEalso have aworkspacefield with the workspace ID, and skills from a repository have asource_id.curl --request GET \--url https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/skills \--header 'Authorization: Bearer <YOUR_API_KEY>' - Get one skill. Without query parameters, the endpoint looks for the skill among the skills that are available to this workspace only. To get a skill from your organization or a deepset skill, pass its
sourceorsource_idfrom the list response:To get a specific version, add thecurl --request GET \--url 'https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/skills/<SKILL_ID>?source=ORG' \--header 'Authorization: Bearer <YOUR_API_KEY>'refquery parameter with the commit hash of the version. - List the versions of a skill, newest first. Each version has a
ref, which is the commit hash of that version:curl --request GET \--url https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/skills/<SKILL_ID>/history \--header 'Authorization: Bearer <YOUR_API_KEY>'
Create a Workspace Skill
Send a POST request with the skill ID and its files. The skill always gets the source WORKSPACE, so the request body has no field to choose the source, and the endpoint ignores a source or source_id you send. Every skill needs a SKILL.md file at its root. The content of each file must be base64-encoded.
curl --request POST \
--url https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/skills \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"id": "web-research",
"files": [
{
"path": "SKILL.md",
"content_base64": "<BASE64_ENCODED_SKILL_MD>"
}
],
"message": "Add the web research skill"
}'
- Replace
<BASE64_ENCODED_SKILL_MD>with the base64-encoded content of yourSKILL.mdfile. On Linux and macOS, you can create it withbase64 < SKILL.md. - The skill ID is the folder name of the skill, in kebab-case.
- The
messagefield is optional. It becomes the commit message of this version.
The response is the created skill. If the workspace already has a skill with this ID, the endpoint returns a 409 error.
Update or Delete a Workspace Skill
- To update a skill, send a
PUTrequest to/api/v2/workspaces/{workspace_id}/skills/{skill_id}with a body that has thefilesand an optionalmessage. Each update creates a new version of the skill. - To delete a skill, send a
DELETErequest to the same path. The endpoint returns the status code 204 if it deletes the skill.
Both endpoints work on skills with the source WORKSPACE only. They return a 404 error if the workspace has no skill with this ID.
Reference a Skill in a Pipeline
When you attach a skill to an Agent in Pipeline Builder, the pipeline YAML gets two entries. If you upload a pipeline with the REST API, you write them yourself:
- A skill toolset in the
toolsof the Agent. The toolset reads the folder that holds the skill files from an environment variable. The platform sets this variable when the pipeline runs. The name has the formDEEPSET_SKILLS_DIR_<COMPONENT_NAME>_<DIGEST>. To get a valid name, attach the skill in Pipeline Builder and copy the name from the YAML. - A top-level
skillsblock. It is not part of a component. It lists the skills of each Agent under the name of the Agent component.
components:
agent:
type: haystack.components.agents.agent.Agent
init_parameters:
tools:
- type: haystack.tools.skills.skill_toolset.SkillToolset
data:
store:
type: haystack.skill_stores.file_system.skill_store.FileSystemSkillStore
init_parameters:
skills_dir:
type: env_var
env_vars:
- DEEPSET_SKILLS_DIR_AGENT_1A2B3C4D
strict: true
skills:
agent:
- id: web-research
hash: <SKILL_VERSION_HASH>
source: WORKSPACE
workspace: <WORKSPACE_ID>
Each skill reference has these fields:
id: The skill ID.hash: The commit hash of the skill version the Agent uses. Take it from thereffield of the version in the skill's history. It's not theshafield of the skill.source:DEEPSET,ORG, orWORKSPACE.workspace: The ID of the workspace. Add it for skills with the sourceWORKSPACE. Skip it for the other sources.source_id: Optional. The ID of the repository the skill lives in, from thesource_idfield of the list response. Add it if your organization has more than one skills repository.
For the Agent to run, the pipeline must use a Haystack version that supports skills. For details, see Add Skills to an Agent.
Related Information
Was this page helpful?