Agent Access

Agent Access lets your AI agents — Claude, GPT, custom automations — read and write to your Kherpi memories programmatically. With a personal API token, an agent can do everything you can: create documents, organize folders, manage document types, and upload media.

Agent Access is available on the Pro plan.

Getting an API Token

Go to Settings → Agent Access
Enter a descriptive name for the token (e.g. "Claude", "My Agent")
Click Create Token
Copy the token immediately — it will only be shown once

You can create up to 5 tokens. Each token has full access to your account — there are no scopes or permission levels.

Using the API

All API endpoints live under /api/v1/ and require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json" \
     https://kherpi.com/api/v1/user

Responses are JSON. The API follows REST conventions: GET to read, POST to create, PUT to update, DELETE to remove.

Available Endpoints

User

Method	Endpoint	Description
GET	`/api/v1/user`	Your profile, plan, and storage usage

Documents

Method	Endpoint	Description
GET	`/api/v1/documents`	List all documents (paginated)
POST	`/api/v1/documents`	Create a new document
GET	`/api/v1/documents/{id}`	Get a single document
PUT	`/api/v1/documents/{id}`	Update a document
DELETE	`/api/v1/documents/{id}`	Soft-delete a document
GET	`/api/v1/documents/trashed`	List trashed documents
POST	`/api/v1/documents/{id}/restore`	Restore from trash
DELETE	`/api/v1/documents/{id}/force`	Permanently delete

Document Versions

Method	Endpoint	Description
GET	`/api/v1/documents/{id}/versions`	List version history
GET	`/api/v1/documents/{id}/versions/{versionId}`	Get a specific version
POST	`/api/v1/documents/{id}/versions/{versionId}/restore`	Restore a version

Document Properties

Method	Endpoint	Description
GET	`/api/v1/documents/{id}/properties`	List custom properties
PUT	`/api/v1/documents/{id}/properties`	Update custom properties

Folders

Method	Endpoint	Description
GET	`/api/v1/folders`	List all folders (nested tree)
POST	`/api/v1/folders`	Create a folder
GET	`/api/v1/folders/{id}`	Get a folder
PUT	`/api/v1/folders/{id}`	Update a folder
DELETE	`/api/v1/folders/{id}`	Delete a folder
POST	`/api/v1/folders/{id}/move`	Move a folder

Document Types

Method	Endpoint	Description
GET	`/api/v1/document-types`	List all document types
POST	`/api/v1/document-types`	Create a document type
GET	`/api/v1/document-types/{id}`	Get a document type
PUT	`/api/v1/document-types/{id}`	Update a document type
DELETE	`/api/v1/document-types/{id}`	Delete a document type

Media

Method	Endpoint	Description
GET	`/api/v1/media`	List uploaded media
POST	`/api/v1/media`	Upload a file
GET	`/api/v1/media/{id}`	Get media details
DELETE	`/api/v1/media/{id}`	Delete a media file

Creating a Document

Here's an example of creating a document with curl:

curl -X POST https://kherpi.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Document",
    "content": "# Hello\n\nThis is my document content in Markdown.",
    "folder_id": 1,
    "document_type_id": 1,
    "status": "draft"
  }'

Required fields: title (max 100 chars) and document_type_id (must reference an existing document type — see below for how to list or create one). Everything else is optional. Omitting either returns 422 Unprocessable Entity with a field is required validation error.

The content field accepts Markdown. Valid status values are draft, final, and archived.

Visibility & Publishing

Three boolean flags control how a document is treated. They can be set on POST (create) and PUT (update):

Flag	Description
`is_public`	Makes the document eligible for your public profile at `/u/{username}/...`
`is_nsfw`	Marks the document as not safe for work — required for adult content
`is_pinned`	Pins the document to the top of its folder

A document is only publicly visible when both is_public is true and status is final. A public draft stays private until you finalize it — handy for staging changes before they go live.

Setting status to final requires the can_publish permission. Finalizing an is_nsfw document additionally requires can_publish_nsfw. Both permissions are granted by the Pro plan; on Free, the API returns 422 Unprocessable Entity with a validation error on status. (The whole API is Pro-only anyway, so in practice all paying users have these — but if your plan is ever downgraded, finalize calls will start failing.)

Publishing a Document

To create and publish a document in one call:

curl -X POST https://kherpi.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Public Note",
    "content": "# Hello world",
    "document_type_id": 1,
    "status": "final",
    "is_public": true
  }'

To publish an existing draft, PUT to the document and flip both flags:

curl -X PUT https://kherpi.com/api/v1/documents/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "final",
    "is_public": true
  }'

To unpublish, set is_public to false (or move the doc back to draft).

Creating a Document Type

A document type defines the shape of a document — its name, icon, and any custom properties (key-value fields) that documents of that type can have.

curl -X POST https://kherpi.com/api/v1/document-types \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recipe",
    "slug": "recipe",
    "icon": "chef-hat",
    "properties": [
      { "name": "Servings", "key": "servings", "type": "number", "is_required": false },
      { "name": "Prep time", "key": "prep_time", "type": "text", "is_required": false }
    ]
  }'

Required fields: name (max 50 chars) and slug (max 50 chars, must match [a-z0-9-]+ — lowercase letters, digits, and hyphens only). The icon and properties fields are optional.

For each entry in properties, name, key (must match [a-z0-9_]+), and type are required. Valid types: text, number, date, datetime, list, checkbox.

The response includes the new type's id, which you can then pass as document_type_id when creating documents.

Rate Limits

The API allows 10 requests per minute per user. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Claude Code Integration

If you use Claude Code (Anthropic's coding CLI), you can install a skill that teaches Claude the full Kherpi API — so you can manage your memories through natural language. See Claude Code Skill for Kherpi for setup instructions.

Managing Tokens

From the Settings → Agent Access page you can:

See all your active tokens with their creation date and last-used timestamp
Revoke any token instantly — the agent will immediately lose access
Create new tokens (up to 5)

Revoked tokens cannot be restored. If you revoke a token by mistake, create a new one and update your agent's configuration.

Security Tips

Treat API tokens like passwords — don't commit them to version control or share them publicly
Give each agent its own token so you can revoke access individually
Use descriptive token names so you know which agent uses which token
Review the "Last used" column periodically to spot unused tokens

10-agent-access