Note

11-claude-code-skill

kherpi ·

Claude Code Skill for Kherpi

If you use Claude Code (Anthropic's CLI for Claude), you can give it a skill that teaches it how to interact with the Kherpi API. With this skill installed, you can ask Claude to create documents, organize folders, upload media, and more — all through natural language.

What is a Claude Code Skill?

Skills are Markdown files that live in your project's .claude/skills/ directory. They give Claude domain-specific knowledge and instructions that it can use when working on your project. A Kherpi API skill teaches Claude the full endpoint reference, authentication pattern, and request/response shapes so it can make API calls on your behalf.

Setup

1. Create the skill directory

mkdir -p .claude/skills/kherpi-api

2. Add your API token to .env

Generate a token from Settings → Agent Access in Kherpi, then add it to your project's .env file:

KHERPI_API_TOKEN=your_token_here

3. Create the skill file

Create .claude/skills/kherpi-api/SKILL.md with the following content:

---
name: kherpi-api
description: Manage documents, folders, document types, and media on kherpi.com via the REST API.
---

# Kherpi API Skill

Use this skill to interact with the Kherpi REST API at `https://kherpi.com/api/v1/`.

## Authentication

Read the `KHERPI_API_TOKEN` value from the project `.env` file. Pass it as a Bearer token:

curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" https://kherpi.com/api/v1/...

## Base URL

https://kherpi.com/api/v1

## Endpoints

### Documents

| Method | Path | Description |
|--------|------|-------------|
| GET | /documents | List (paginated) |
| POST | /documents | Create |
| GET | /documents/{id} | Show |
| PUT | /documents/{id} | Update |
| DELETE | /documents/{id} | Soft-delete |
| GET | /documents/trashed | List trashed |
| POST | /documents/{id}/restore | Restore |
| DELETE | /documents/{id}/force | Permanently delete |

Query params (index): search, folder_id, document_type_id, status, sort_by, sort_dir, per_page

Create fields:
- title (required, string, max 100)
- content (optional, Markdown string)
- status (optional: draft, final, archived)
- is_public (optional, boolean)
- is_nsfw (optional, boolean)
- is_pinned (optional, boolean)
- folder_id (optional, must exist)
- document_type_id (required, must exist)
- properties (optional, key-value object)

Publishing: a document is publicly visible only when both `is_public=true` AND `status=final`. Setting `status=final` requires the `can_publish` permission on the user's plan; the API returns 422 otherwise.

### Document Versions

| Method | Path | Description |
|--------|------|-------------|
| GET | /documents/{id}/versions | List history |
| GET | /documents/{id}/versions/{versionId} | Show version |
| POST | /documents/{id}/versions/{versionId}/restore | Restore version |

### Document Properties

| Method | Path | Description |
|--------|------|-------------|
| GET | /documents/{id}/properties | List |
| PUT | /documents/{id}/properties | Bulk update |

### Folders

| Method | Path | Description |
|--------|------|-------------|
| GET | /folders | List (nested tree) |
| POST | /folders | Create |
| GET | /folders/{id} | Show |
| PUT | /folders/{id} | Update |
| DELETE | /folders/{id} | Delete |
| POST | /folders/{id}/move | Move |

### Document Types

| Method | Path | Description |
|--------|------|-------------|
| GET | /document-types | List |
| POST | /document-types | Create |
| GET | /document-types/{id} | Show |
| PUT | /document-types/{id} | Update |
| DELETE | /document-types/{id} | Delete |

### Media

| Method | Path | Description |
|--------|------|-------------|
| GET | /media | List |
| POST | /media | Upload (multipart, max 2MB, jpg/png/gif/webp) |
| GET | /media/{id} | Show |
| DELETE | /media/{id} | Delete |

### User

| Method | Path | Description |
|--------|------|-------------|
| GET | /user | Profile, plan, storage |

## Rate Limit

10 requests per minute per user. Exceeding this returns `429 Too Many Requests`.

## Workflow

1. Read KHERPI_API_TOKEN from .env
2. Use curl with Bearer auth and Accept: application/json
3. For JSON bodies, add Content-Type: application/json
4. For file uploads, use -F "file=@path"
5. Check response for errors before proceeding

You can customize the skill content to match your specific Kherpi instance URL and add any project-specific conventions.

Usage

Once the skill is installed, you can ask Claude things like:

Claude will read the skill, grab your token from .env, and make the appropriate API calls.

Security Notes