Skills API
Use skills to store reusable knowledge that Assistant can retrieve during conversations. Skills contain instructions, procedures, or reference material that Assistant draws on when relevant to a user’s question.
Skills have two scopes:
- Tenant skills are visible to all users in the organization. This is the default scope.
- User skills are visible only to the identity that created them. When a service account creates a user skill, only that service account can see it. You can’t create user skills on behalf of other users.
Examples use the base URL and service account token described in Grafana Assistant HTTP API reference.
Create a skill
Create a new skill.
Endpoint
POST /skills
Permissions
Request
Send a JSON request body.
Allowed tools object
The allowedTools field is an array of tools that Assistant can run without asking for user approval when this skill is invoked. Each entry identifies a tool on a specific MCP server integration.
{
"name": "Incident triage checklist",
"body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes",
"scope": "tenant",
"includeInKnowledgebase": true,
"allowedTools": [
{
"integrationId": "d6e4f5a7-8901-2345-bdef-167890123456",
"toolName": "search_docs"
}
]
}Response
{
"status": "success",
"data": {
"id": "b4c2d3e5-6789-0123-bcde-f45678901234",
"name": "Incident triage checklist",
"body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes",
"created": "2025-11-15T09:00:00Z",
"modified": "2025-11-15T09:00:00Z",
"createdBy": "sa-5594@serviceaccount.grafana",
"includeInKnowledgebase": true,
"scope": "tenant"
}
}Examples
curl -X POST "${ASSISTANT_API_URL}/skills" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
-d '{
"name": "Incident triage checklist",
"body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes",
"scope": "tenant"
}'List skills
Retrieve skills with optional filtering and pagination.
Endpoint
GET /skills
Permissions
Request
Response
{
"status": "success",
"data": {
"skills": [
{
"id": "b4c2d3e5-6789-0123-bcde-f45678901234",
"name": "Incident triage checklist",
"body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes",
"created": "2025-11-15T09:00:00Z",
"modified": "2025-11-15T09:00:00Z",
"createdBy": "sa-5594@serviceaccount.grafana",
"includeInKnowledgebase": true,
"scope": "tenant"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0
}
}
}Examples
curl -X GET "${ASSISTANT_API_URL}/skills?scope=tenant&limit=10" \
-H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"Get a skill
Retrieve a single skill by ID.
Endpoint
GET /skills/{id}
Permissions
Request
Response
{
"status": "success",
"data": {
"id": "b4c2d3e5-6789-0123-bcde-f45678901234",
"name": "Incident triage checklist",
"body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes",
"created": "2025-11-15T09:00:00Z",
"modified": "2025-11-15T09:00:00Z",
"createdBy": "sa-5594@serviceaccount.grafana",
"includeInKnowledgebase": true,
"scope": "tenant"
}
}Examples
SKILL_ID="b4c2d3e5-6789-0123-bcde-f45678901234"
curl -X GET "${ASSISTANT_API_URL}/skills/${SKILL_ID}" \
-H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"Update a skill
Update an existing skill. Only the fields you include in the request body are changed.
Endpoint
PUT /skills/{id}
Permissions
To change a skill’s scope, the service account needs write permissions for both scopes. Only the skill’s creator can change its scope.
Request
Send a JSON request body with the fields to update.
Response
The response contains the full updated skill.
{
"status": "success",
"data": {
"id": "b4c2d3e5-6789-0123-bcde-f45678901234",
"name": "Incident triage checklist",
"body": "Updated triage steps...",
"created": "2025-11-15T09:00:00Z",
"modified": "2025-11-20T14:15:00Z",
"createdBy": "sa-5594@serviceaccount.grafana",
"updatedBy": "sa-5594@serviceaccount.grafana",
"includeInKnowledgebase": true,
"scope": "tenant"
}
}Examples
Update a skill’s content:
SKILL_ID="b4c2d3e5-6789-0123-bcde-f45678901234"
curl -X PUT "${ASSISTANT_API_URL}/skills/${SKILL_ID}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
-d '{
"body": "Updated triage steps:\n1. Check recent deployments in the last 2 hours\n2. Review error rate dashboards\n3. Check upstream dependencies"
}'Delete a skill
Permanently delete a skill.
Endpoint
DELETE /skills/{id}
Permissions
Request
Response
A successful deletion returns HTTP 204 with no response body.
Examples
SKILL_ID="b4c2d3e5-6789-0123-bcde-f45678901234"
curl -X DELETE "${ASSISTANT_API_URL}/skills/${SKILL_ID}" \
-H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
