Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

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.

Permissions

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.

TaskMethod and path
List the skills you can use in the workspaceGET /api/v2/workspaces/{workspace_id}/skills
Get a skillGET /api/v2/workspaces/{workspace_id}/skills/{skill_id}
List the versions of a skillGET /api/v2/workspaces/{workspace_id}/skills/{skill_id}/history
Create a workspace skillPOST /api/v2/workspaces/{workspace_id}/skills
Update a workspace skillPUT /api/v2/workspaces/{workspace_id}/skills/{skill_id}
Delete a workspace skillDELETE /api/v2/workspaces/{workspace_id}/skills/{skill_id}

List and Get Skills​

  1. List the skills. The response includes the skills of the DEEPSET, ORG, and WORKSPACE sources. Skills with the source WORKSPACE also have a workspace field with the workspace ID, and skills from a repository have a source_id.
    curl --request GET \
    --url https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/skills \
    --header 'Authorization: Bearer <YOUR_API_KEY>'
  2. 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 source or source_id from the list response:
    curl --request GET \
    --url 'https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/skills/<SKILL_ID>?source=ORG' \
    --header 'Authorization: Bearer <YOUR_API_KEY>'
    To get a specific version, add the ref query parameter with the commit hash of the version.
  3. 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 your SKILL.md file. On Linux and macOS, you can create it with base64 < SKILL.md.
  • The skill ID is the folder name of the skill, in kebab-case.
  • The message field 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 PUT request to /api/v2/workspaces/{workspace_id}/skills/{skill_id} with a body that has the files and an optional message. Each update creates a new version of the skill.
  • To delete a skill, send a DELETE request 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 tools of 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 form DEEPSET_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 skills block. 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 the ref field of the version in the skill's history. It's not the sha field of the skill.
  • source: DEEPSET, ORG, or WORKSPACE.
  • workspace: The ID of the workspace. Add it for skills with the source WORKSPACE. Skip it for the other sources.
  • source_id: Optional. The ID of the repository the skill lives in, from the source_id field 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.