This page documents the REST API endpoints exposed by ɳSelf plugins. These endpoints are internal to your ɳSelf stack and accessed via Nginx reverse proxy. All endpoints require authentication unless noted otherwise.
Base URL: https://api.yourdomain.com (or http://localhost in development)
Plugin REST endpoints use two auth mechanisms:
Method Header When Used JWT Bearer Authorization: Bearer {token}User-facing endpoints Internal Token X-Internal-Token: {secret}Plugin-to-plugin communication
Internal tokens are configured via PLUGIN_INTERNAL_SECRET in .env.secrets. Plugin-to-plugin calls (e.g., mux calling claw) use MUX_CLAW_SHARED_SECRET or the generic internal token.
Method Path Description POST/claw/messageSend a message to the AI assistant. Returns AI response with tool results. GET/claw/threadsList conversation threads for the authenticated user. GET/claw/threads/{id}Get a specific thread with messages. DELETE/claw/threads/{id}Delete a thread and its messages.
Method Path Description GET/claw/memoriesList stored memories. Supports type filter (fact, preference, decision, pattern, relationship). POST/claw/memoriesCreate a memory entry manually. DELETE/claw/memories/{id}Delete a specific memory. POST/claw/memories/bulk-deleteDelete multiple memories by ID. GET/claw/memories/exportExport all memories as JSON. POST/claw/memories/importImport memories from JSON. POST/claw/memories/searchSemantic search over memories (pgvector cosine similarity).
Method Path Description GET/claw/personasList all personas. POST/claw/personasCreate a new persona. PUT/claw/personas/{id}Update a persona. DELETE/claw/personas/{id}Delete a persona.
Method Path Description GET/claw/toolsList all registered tools (native + manifest + integration).
Method Path Description GET/claw/budgetGet current budget status (daily/monthly limits, current spend). POST/claw/budgetSet or update budget limits.
Method Path Description GET/claw/email/prioritiesGet email priority classifications (action_required, time_sensitive, fyi, junk).
Method Path Description GET/claw/contactsList contacts. POST/claw/contactsCreate a contact. PUT/claw/contacts/{id}Update a contact. DELETE/claw/contacts/{id}Delete a contact. GET/claw/contacts/{id}/vcardExport contact as vCard 3.0.
Method Path Description GET/claw/integrationsList configured integrations. POST/claw/integrationsCreate an integration (with SSRF validation on base_url). PUT/claw/integrations/{id}Update an integration. DELETE/claw/integrations/{id}Delete an integration. POST/claw/integrations/{id}/testTest integration health.
Method Path Description GET/claw/transactionsQuery financial transactions. Filters: keyword, category, date range, user_id. GET/claw/transactions/summary6-month totals, top 5 vendors (30d), category breakdown.
Method Path Description GET/claw/proactive/logGet proactive notification history.
Method Path Description GET/claw/goalsList goals. POST/claw/goalsCreate a goal. PUT/claw/goals/{id}Update a goal. DELETE/claw/goals/{id}Delete a goal.
Method Path Description GET/claw/health/monitoringCheck Prometheus, Loki, Alertmanager health.
Method Path Description POST/claw/pair/openOpen pairing window (internal auth via X-Internal-Secret). GET/claw/pair/statusCheck pairing window status. GET/claw/pairGet pairing code (404 when window closed). POST/claw/pair/directDirect pairing with HMAC-SHA256 4-word phrase. GET/claw/pair/direct/statusCheck direct pairing status.
Method Path Description GET/claw/onboarding/statusCheck onboarding completion. POST/claw/onboarding/answerSubmit an onboarding answer. POST/claw/onboarding/restartRestart onboarding flow.
Method Path Description GET/claw/usage30-day AI usage by model (tokens, cost, routed_by).
Method Path Description POST/claw/telegram/webhookTelegram bot webhook handler. Gated by CLAW_TG_ALLOWED_USERS.
Method Path Description GET/claw/memory/roomsList memory rooms with counts and health scores. POST/claw/memory/roomsCreate a named memory room. PUT/claw/memory/rooms/{id}Update room name or ordering. DELETE/claw/memory/rooms/{id}Delete room (memories return to default). POST/claw/memory/rooms/{id}/assignAssign memory IDs to a room.
Method Path Description GET/claw/knowledge/healthBrain health check report (stale, orphan, duplicate detection). GET/claw/knowledge/statsKnowledge graph statistics (node count, edges, avg connections). GET/claw/knowledge/exportExport knowledge graph. Query param format=obsidian or format=json. GET/claw/ingestion/queueList ingestion pipeline jobs. POST/claw/ingestion/startStart ingestion from URL or file. DELETE/claw/ingestion/{id}Cancel an ingestion job.
Method Path Description GET/claw/decisionsList recorded decisions. POST/claw/decisionsRecord a new decision with context. PUT/claw/decisions/{id}Update decision outcome.
Method Path Description GET/claw/routing/rulesList smart routing rules. POST/claw/routing/rulesCreate a routing rule. PUT/claw/routing/rules/{id}Update a routing rule. DELETE/claw/routing/rules/{id}Delete a routing rule.
Method Path Description POST/claw/image/generateGenerate image from text prompt. Supports provider override. GET/claw/image/jobsList image generation jobs and statuses. GET/claw/image/jobs/{id}Get specific job result with image URL.
Method Path Description GET/claw/model/recommendGet model recommendation for a given query type. POST/claw/sessions/{id}/featuresToggle session feature flags. POST/claw/sessions/{id}/summarizeCompress and summarize session context.
Method Path Description GET/claw/marketplace/personasBrowse community personas (no auth required). POST/claw/marketplace/personasPublish a persona to the marketplace. POST/claw/marketplace/personas/{id}/installInstall a marketplace persona.
Method Path Description GET/claw/agents/dashboardAgent metrics with sparkline data for all personas. GET/claw/agents/statusLive per-agent status (active, idle, error). GET/claw/crewsList agent crew configurations. POST/claw/crewsCreate an agent crew.
Method Path Description GET/claw/habitsList habit definitions. POST/claw/habitsCreate a habit. PUT/claw/habits/{id}Update habit settings. POST/claw/habits/{id}/logLog daily habit completion. GET/claw/tutor/cardsList tutor flashcards. POST/claw/tutor/quizStart a quiz session. GET/claw/career/cvGet structured CV data. PUT/claw/career/cvUpdate CV data. GET/claw/career/suggestionsGet career suggestions.
Method Path Description GET/claw/health/checkinHealth coach check-in. GET/claw/health/summaryHealth metrics summary.
Method Path Description GET/claw/reflectionsList daily reflections. POST/claw/reflectionsCreate a reflection entry.
Method Path Description GET/claw/promptsList prompt library templates. POST/claw/promptsCreate a prompt template. POST/claw/prompts/{id}/chainChain prompts for sequential execution. GET/claw/workflows/templatesList workflow templates. POST/claw/workflows/templatesCreate a workflow template. POST/claw/workflows/runExecute a workflow.
Method Path Description GET/claw/projects/filesList project files. POST/claw/projects/filesUpload a project file. DELETE/claw/projects/files/{id}Delete a project file.
Method Path Description GET/claw/historyConversation history with search and date filters. GET/claw/galleryImage gallery with generated images.
Method Path Description POST/ai/completeRoute a completion request to the best model (4-tier routing). POST/ai/embeddingsGenerate vector embeddings for text. GET/ai/statusProvider health and routing status. GET/ai/providersList configured AI providers and their status. GET/ai/tokensList caller tokens (per-namespace auth). POST/ai/tokensCreate a caller token. DELETE/ai/tokens/{id}Revoke a caller token. GET/ai/accountsList OAuth AI accounts. POST/ai/accounts/refreshForce refresh OAuth tokens. POST/ai/email-eventReceive forwarded email metadata from mux rules.
External API (port 18900): OpenAI-compatible API for third-party integrations. Uses caller tokens for auth.
Method Path Description GET/mux/messagesQuery email history. Filters: ILIKE search on from/subject/body, date range, account. Internal auth. POST/mux/tokens/importImport OAuth refresh token for a Gmail account. Internal auth. GET/mux/auto-reply/auditAuto-reply audit log. Filter by rule. POST/mux/pending-replies/{id}/approveApprove a pending auto-reply draft. POST/mux/pending-replies/{id}/discardDiscard a pending auto-reply draft.
The claw-budget plugin provides standalone budget management that works independently of the claw plugin:
Method Path Description GET/claw-budget/statusCurrent spend vs limits (daily + monthly). POST/claw-budget/limitsSet daily/monthly token budget limits. GET/claw-budget/historySpend history over time.
Method Path Description POST/voice/ttsText-to-speech. Providers: Piper (local), ElevenLabs. POST/voice/sttSpeech-to-text via whisper.cpp. POST/voice/call/outboundInitiate outbound call via Twilio. GET/voice/call/statusCheck call status. GET/voice/routing/statusCurrent LLM routing tier (standard vs realtime). POST/voice/routing/set-tierSet voice LLM routing tier.
Method Path Description GET/browser/tabsList open browser tabs. POST/browser/actionExecute browser action. Actions: navigate, click, type, extract, screenshot, wait_for, evaluate, get_cookies. GET/browser/allowlistList allowed URLs. POST/browser/allowlistAdd URL to allowlist.
SSRF protection blocks all RFC-1918 and private IP addresses.
Method Path Description GET/google/gmail/messagesSearch Gmail messages. GET/google/gmail/message/{id}Get full email content. GET/google/calendar/eventsList calendar events. POST/google/calendar/eventsCreate a calendar event. GET/google/calendar/freebusyFind free time slots. GET/google/drive/filesList Drive files. POST/google/sheets/appendAppend row to a Google Sheet. GET/google/sheets/readRead data from a Google Sheet.
Primary account resolution: GOOGLE_PRIMARY_USER_ID env var or first database row.
Method Path Description POST/notify/sendSend notification via configured channels. GET/notify/channelsList notification channels. POST/notify/channelsCreate a channel (Telegram, webhook). DELETE/notify/channels/{id}Delete a channel.
Method Path Description GET/cron/jobsList scheduled jobs. POST/cron/jobsCreate a cron job (timezone-aware, DB persistence). DELETE/cron/jobs/{id}Delete a job. POST/cron/jobs/{id}/runTrigger a job immediately.
Method Path Description POST/post/publishPublish to one or more platforms (immediate or scheduled). GET/post/accountsList connected publishing accounts. GET/post/queueGet scheduled post queue.
Supported platforms: WordPress, Ghost, Twitter, Telegram channel, Dev.to, Hashnode.
These endpoints use X-Internal-Token auth and are not meant for direct user access.
Method Path Plugin Description POST/internal/classifyclaw Classify a message (used by mux). Auth: MUX_CLAW_SHARED_SECRET. GET/internal/healthall Plugin health check. Returns 200 if healthy.
When plugins are installed, the CLI auto-generates PLUGIN_{NAME}_INTERNAL_URL environment variables:
Variable Default PLUGIN_AI_INTERNAL_URLhttp:/nself:18900PLUGIN_CLAW_INTERNAL_URLhttp:/nself:18901PLUGIN_MUX_INTERNAL_URLhttp:/nself:18902PLUGIN_VOICE_INTERNAL_URLhttp:/nself:18903PLUGIN_BROWSER_INTERNAL_URLhttp:/nself:18904PLUGIN_GOOGLE_INTERNAL_URLhttp:/nself:18905PLUGIN_NOTIFY_INTERNAL_URLhttp:/nself:18906PLUGIN_CRON_INTERNAL_URLhttp:/nself:18907
Plugins use these URLs to communicate with each other over the Docker bridge network.
All endpoints return standard HTTP status codes:
Code Meaning 200 Success 400 Bad request (validation error) 401 Unauthorized (missing or invalid token) 403 Forbidden (insufficient permissions or tier) 404 Not found 429 Rate limited 500 Internal server error
Error body format:
"error" : " human-readable message " ,
"code" : " MACHINE_READABLE_CODE "
← Home | _Sidebar
