--- title: "ToolPiper API Reference — ModelPiper" description: "API documentation for ToolPiper, the macOS menu bar app for local AI model inference. REST API endpoints, model management, and MCP server integration." canonical: "https://modelpiper.com/docs/toolpiper/" --- # ToolPiper API Reference — ModelPiper > API documentation for ToolPiper, the macOS menu bar app for local AI model inference. REST API endpoints, model management, and MCP server integration. # ToolPiper API Offline ToolPiper is the local AI server that powers ModelPiper. It runs on your Mac, manages inference engines, and exposes an OpenAI-compatible API at `localhost:9998`. Base URL`http://localhost:9998/v1`Spec`GET /v1/openapi.json` ## How It Works ModelPiper is the web app you're looking at right now. It talks to ToolPiper, a native macOS app running in the background. ToolPiper manages the actual AI engines — llama.cpp for LLMs, FluidAudio for speech, CoreML for images, and more. When you create a **Provider** in ModelPiper, you're setting up a configuration that pairs an AI model with a specific engine. For example: _Use the Llama 3.2 3B model via llama.cpp_ or _Use Parakeet for speech-to-text via FluidAudio._ Each provider becomes a usable endpoint on the ToolPiper API. ModelPiper uses an internal session key to stay connected to ToolPiper — you don't need to think about that. But if you want to build your own app on top of ToolPiper, you'll need a **Developer Token**. ## Developer Tokens Pro A dev token lets you use ToolPiper from your own code, just like an OpenAI API key. Create one, drop it into any OpenAI-compatible SDK, and point the base URL at `localhost:9998/v1`. That's it. ToolPiper is offline. Start it to manage tokens. ## Claude Code Zero-config Wire ToolPiper into Claude Code with one click. We generate a dev token, write `~/.claude/settings.json`, and register ToolPiper as an MCP server. Claude Code's `/model` picker shows every endpoint you've configured here. [ Recipe · Free, on-device Apple Intelligence Neural Engine inference. No API key, no quota. ](/recipes/claude-code-apple-intelligence)[ Recipe · 32K · Tool use Local Qwen via llama.cpp Best capability/privacy balance. ](/recipes/claude-code-local-qwen)[ Recipe · BYOK OpenAI with your key Keychain-locked; never in dotfiles or logs. ](/recipes/claude-code-byok-openai)[ Recipe · Conversational Switch providers in chat "Use my local one" — endpoint\_set MCP tool. ](/recipes/claude-code-cross-provider) New to all of this? See the [comparison vs Ollama / vLLM / LM Studio](/compare/claude-code-backends). ToolPiper is offline. Start it to connect Claude Code. ## Anthropic Proxy Backend Phase 1 plumbing ToolPiper will expose `POST /v1/messages` as an Anthropic-shape proxy so Claude Code (and any Anthropic-compatible client) can use any provider you've configured. Pick the global backend below, or bind a specific provider per token in the table above. ToolPiper is offline. Start it to configure the proxy backend. ## Quick Start Drop-in replacement for the OpenAI SDK — just change the base URL and API key. Questions? [@ModelPiper](https://x.com/ModelPiper) on X. curlPythonTypeScriptAny SDK ``` curl http://localhost:9998/v1/chat/completions \ -H "Authorization: Bearer tp_YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "llama-3.2-3b", "messages": [{"role": "user", "content": "Hello!"}] }' ``` ## MCP Server 147 tools ToolPiper is also an MCP server. Install categories individually to control which tools your AI client sees — saves context tokens. - `core`12LLM inference, TTS, STT, embeddings, OCR - `analysis`8Image/text analysis, RAG, upscaling - `browser`19Browser automation, scraping, assertions - `testing`6PiperTest CRUD and execution - `motion`5Pose estimation, stream processing - `outreach`12GitHub, HN, Reddit, X, content queue - `system`29macOS system actions - `video`17Video creator pipeline - `oauth`4OAuth connection management - `sieve`4MediaPiper sieve cache inspection - `filesystem`13File read/write, git operations, shell commands See [MCP docs](/docs/mcp) for install commands, profiles, and full tool reference. ## Endpoints ### Inference OpenAI-compatible chat completions and model listing - GET`/v1/models`List available models - POST`/v1/chat/completions`Create chat completion (streaming supported) ### Audio Speech-to-text and text-to-speech - POST`/v1/audio/transcriptions`Transcribe audio (STT) - POST`/v1/audio/speech`Synthesize speech (TTS), supports voice cloning ### Image & Video CoreML-powered image and video upscaling (PiperSR) - POST`/v1/images/upscale`Upscale image 2x/4x via CoreML (returns PNG) - POST`/v1/video/upscale`Upscale video 2x via PiperSR (base64 in/out) - POST`/v1/video/upscale/url`Upscale video 2x from URL - POST`/v1/video/upscale/file`Upscale video 2x using file paths (no base64 overhead) - GET`/v1/video/upscale/{id}`Check upscale job status - GET`/v1/video/upscale/{id}/result`Download upscaled video result (streaming) - POST`/v1/benchmark/upscale`Run PiperSR benchmark suite (A–G) ### Pose Estimation Body keypoint detection for ControlNet, AnimateDiff, DWPose - POST`/v1/pose/detect`Detect body poses — skeleton image + JSON keypoints - POST`/v1/pose/activate`Activate a pose detection model - GET`/v1/pose/active`Get currently active pose detector - GET`/v1/pose/formats`List backends, renderers, and topologies - GET`/v1/pose/models`Available pose detection models - POST`/v1/pose/stream/start`Start the pose streaming WebSocket (on-demand, returns port) - POST`/v1/pose/stream/stop`Stop the pose streaming WebSocket - GET`/v1/pose/stream/status`Check if pose stream WebSocket is running + port ### Stream Processing Real-time frame processing from WebSocket sources - POST`/v1/stream/start`Start stream session (connect to frame source) - POST`/v1/stream/stop`Stop a stream session - GET`/v1/stream/status`Active sessions and frame stats ### RAG Retrieval-Augmented Generation - GET`/v1/rag/collections`List collections - POST`/v1/rag/collections`Create a collection - GET`/v1/rag/collections/{id}`Get collection details - PUT`/v1/rag/collections/{id}`Update a collection - DELETE`/v1/rag/collections/{id}`Delete a collection - GET`/v1/rag/collections/{id}/chunks`List chunks (paginated) - POST`/v1/rag/collections/{id}/ingest`Start document ingestion - GET`/v1/rag/collections/{id}/ingest/status`Ingestion progress - POST`/v1/rag/collections/{id}/ingest/cancel`Cancel ingestion - POST`/v1/rag/query`Semantic search across collections - POST`/v1/rag/browse-folder`Browse folder for ingestion ### Cloud Proxy Keychain-backed cloud API proxy - POST`/v1/cloud/proxy`Proxy request to cloud provider - POST`/v1/cloud/api-key`Save API key to Keychain - GET`/v1/cloud/api-key`Load API key from Keychain - DELETE`/v1/cloud/api-key`Delete API key from Keychain ### Models Model management and HuggingFace integration - GET`/model-configs`List curated model presets - POST`/model-configs/install`Install a model by preset ID - GET`/models`List downloaded models - GET`/models/{id}`Get model details - DELETE`/models/{id}`Delete a downloaded model - GET`/models/storage`Disk usage for models - POST`/models/scan`Scan filesystem for new models - GET`/models/search`Search HuggingFace - POST`/models/download`Download from HuggingFace - GET`/models/downloads`List active downloads - DELETE`/models/downloads/{id}`Cancel a download - GET`/models/hf/{owner}/{repo}/files`List HuggingFace repo files ### Engine Inference engine control - GET`/engine/status`Engine and backend status - POST`/engine/load`Load a model - POST`/engine/unload`Unload a model or stop engine - GET`/models/state`Per-model runtime states ### Auth Developer tokens (Pro) - GET`/v1/tokens`List dev tokens (masked) - POST`/v1/tokens`Create a dev token - PATCH`/v1/tokens/{id}`Update token label, origins, or endpoint binding - DELETE`/v1/tokens/{id}`Revoke a dev token ### Anthropic Proxy Settings for the Anthropic Messages proxy at /v1/messages - GET`/v1/settings/anthropic-proxy`Read global Anthropic proxy settings - PATCH`/v1/settings/anthropic-proxy`Update global proxy backend selection ### Apple Vision On-device image analysis via Apple Vision framework - POST`/v1/apple/ocr`Text recognition (20+ languages, handwriting) - GET`/v1/apple/ocr/languages`List supported OCR languages - POST`/v1/apple/barcode`Barcode and QR code detection - POST`/v1/apple/classify`Image classification (1000+ categories) - POST`/v1/apple/face-detect`Face detection with pose angles - POST`/v1/apple/saliency`Attention or objectness saliency maps - POST`/v1/apple/rectangles`Rectangle and document detection - POST`/v1/apple/feature-print`Image feature vectors for similarity - POST`/v1/apple/body-pose`Human body skeletal keypoints - POST`/v1/apple/hand-pose`Hand and finger joint detection - POST`/v1/apple/animals`Cat and dog detection - POST`/v1/apple/horizon`Horizon angle detection - POST`/v1/apple/document`Document boundary detection ### Apple NLP On-device text analysis via Apple Natural Language framework - POST`/v1/apple/nlp/language`Language detection with confidence scores - POST`/v1/apple/nlp/sentiment`Sentiment analysis (-1 to +1) - POST`/v1/apple/nlp/entities`Named entity recognition (people, places, orgs) - POST`/v1/apple/nlp/tokenize`Text tokenization (word, sentence, paragraph) - POST`/v1/apple/nlp/lemmatize`Word lemmatization (running → run) - POST`/v1/apple/nlp/pos`Part-of-speech tagging ### Scrape CDP-based web scraping with framework-aware readiness — up to 7 output formats from a single page load - POST`/v1/scrape`Start a scrape job (markdown, text, readability, axTree, html, links, screenshot) - GET`/v1/scrape`List recent scrape jobs - GET`/v1/scrape/{jobId}`Get scrape job status and result - GET`/v1/youtube/transcript`Get YouTube video transcript (captions) ### Browser (CDP) Chrome DevTools Protocol automation — AX selectors, self-healing, mutation diffing - GET`/v1/browser/status`Connection status and current page - GET`/v1/browser/full-status`Extended status with pages and channels - GET`/v1/browser/channels`Available Chrome channels (dev, canary, stable) - POST`/v1/browser/connect`Connect to Chrome (host + port) - POST`/v1/browser/disconnect`Disconnect from Chrome - GET`/v1/browser/pages`List available browser pages - POST`/v1/browser/select-page`Switch to a page by ID - POST`/v1/browser/new-tab`Open a new tab - POST`/v1/browser/close-tab`Close a tab - GET`/v1/browser/snapshot`Accessibility tree of current page - GET`/v1/browser/screenshot`Screenshot as base64 PNG - POST`/v1/browser/action`Perform action (click, fill, navigate, etc.) - POST`/v1/browser/assert`Assert page state (visible, text, url, etc.) - POST`/v1/browser/heal`Heal a broken selector - POST`/v1/browser/evaluate`Execute JavaScript in page - POST`/v1/browser/resize`Resize browser viewport - POST`/v1/browser/dialog`Handle JavaScript dialogs - GET`/v1/browser/console`Recent console messages (last 100) - POST`/v1/browser/record/start`Start recording user interactions - POST`/v1/browser/record/stop`Stop recording, return action log - GET`/v1/browser/record/stream`SSE stream of live recorded actions - GET`/v1/browser/network`List captured network requests - GET`/v1/browser/network/status`Network logging status - POST`/v1/browser/network/enable`Enable network logging - POST`/v1/browser/network/disable`Disable network logging - DELETE`/v1/browser/network`Clear network log - GET`/v1/browser/network/{requestId}/body`Get request/response body - GET`/v1/browser/storage`Get cookies, localStorage, sessionStorage - DELETE`/v1/browser/storage`Clear browser storage - POST`/v1/browser/storage/cookie`Set a cookie - POST`/v1/browser/storage/local`Set localStorage value - POST`/v1/browser/storage/session`Set sessionStorage value - POST`/v1/browser/trace/start`Start performance trace - POST`/v1/browser/trace/stop`Stop performance trace - GET`/v1/browser/trace/status`Trace status - GET`/v1/browser/metrics`Get performance metrics - GET`/v1/browser/coverage/status`Code coverage status - POST`/v1/browser/coverage/start`Start JS/CSS code coverage - POST`/v1/browser/coverage/stop`Stop coverage collection - GET`/v1/browser/intercept/status`Request interception status - POST`/v1/browser/intercept/enable`Enable request interception - POST`/v1/browser/intercept/disable`Disable request interception - GET`/v1/browser/mocks`List mock rules - POST`/v1/browser/mocks`Create mock rule - DELETE`/v1/browser/mocks`Clear all mock rules - DELETE`/v1/browser/mocks/{id}`Delete a mock rule - GET`/v1/browser/webauthn/status`WebAuthn authenticator status - POST`/v1/browser/webauthn/enable`Enable virtual authenticator - POST`/v1/browser/webauthn/disable`Disable virtual authenticator - GET`/v1/browser/webauthn/credentials`List WebAuthn credentials - DELETE`/v1/browser/webauthn/credentials/{id}`Delete a WebAuthn credential - POST`/v1/browser/webauthn/verify`Set credential as verified - POST`/v1/browser/autofill/credit-card`Set credit card autofill data - POST`/v1/browser/autofill/address`Set address autofill data ### Testing (PiperTest) Visual test session management, execution, and coverage - GET`/v1/test-sessions`List all test sessions - POST`/v1/test-sessions`Create a test session - POST`/v1/test-sessions/import`Import a test session - GET`/v1/test-sessions/{id}`Get test session by ID - PUT`/v1/test-sessions/{id}`Update a test session - DELETE`/v1/test-sessions/{id}`Delete a test session - POST`/v1/test-sessions/{id}/run`Run a saved test session - POST`/v1/test-sessions/{id}/run/cancel`Cancel a running test - GET`/v1/test-sessions/{id}/probe`Get saved interaction map - POST`/v1/test-sessions/{id}/coverage`Get combined coverage report - POST`/v1/test-sessions/{id}/export`Export to Playwright/Cypress - POST`/v1/tests/run`Run inline test steps - POST`/v1/browser/probe/scan`Scan page for interaction coverage ### Video Creator Screenplays, recording, rendering, and narration - GET`/v1/video/screenplays`List screenplays - POST`/v1/video/screenplays`Create a screenplay - GET`/v1/video/screenplays/{id}`Get screenplay details - PUT`/v1/video/screenplays/{id}`Update a screenplay - DELETE`/v1/video/screenplays/{id}`Delete a screenplay - GET`/v1/video/screenplays/{id}/storyboard`Get screenplay storyboard - POST`/v1/video/screenplays/{id}/rehearse`Dry-run a screenplay - POST`/v1/video/screenplays/{id}/record`Record screenplay to video - POST`/v1/video/screenplays/{id}/record/cancel`Cancel recording - POST`/v1/video/screenplays/{id}/render`Render with styling/overlays - POST`/v1/video/screenplays/{id}/render/cancel`Cancel rendering - POST`/v1/video/screenplays/{id}/narrate`Generate TTS narration - POST`/v1/video/screenplays/{id}/narrate/cancel`Cancel narration - GET`/v1/video/screenplays/{id}/timeline`Get timeline map - POST`/v1/video/screenplays/{id}/edit/screenplay`Edit screenplay structure - POST`/v1/video/screenplays/{id}/edit/composition`Edit composition settings - POST`/v1/video/screenplays/{id}/edit/narration`Edit narration settings ### Conversations Chat conversation persistence - GET`/v1/conversations`List conversations - POST`/v1/conversations`Create a conversation - GET`/v1/conversations/{id}`Get conversation - PUT`/v1/conversations/{id}`Update conversation - DELETE`/v1/conversations/{id}`Delete conversation - POST`/v1/conversations/{id}/rename`Rename conversation ### OAuth OAuth 2.1 connection management for third-party services - POST`/v1/oauth/connect`Start OAuth consent flow (Google, Reddit, GitHub, X) - POST`/v1/oauth/connect/service-account`Connect Google service account - GET`/v1/oauth/status`Check all OAuth connection statuses - GET`/v1/oauth/status/{provider}`Check single provider status - DELETE`/v1/oauth/disconnect/{provider}`Disconnect and revoke tokens ### Outreach GitHub monitoring, content queue, HN, Reddit, X/Twitter, mentions - GET`/v1/outreach/github/repos`List GitHub repos - GET`/v1/outreach/github/activity`GitHub repo activity - GET`/v1/outreach/github/compare`Compare two Git refs - GET`/v1/outreach/github/poll-state`Get GitHub polling state - POST`/v1/outreach/github/poll-state`Update GitHub polling state - GET`/v1/outreach/mentions`Get real-time web mentions - GET`/v1/outreach/mentions/rules`List mention rules - POST`/v1/outreach/mentions/rules`Create mention rule - DELETE`/v1/outreach/mentions/rules/{id}`Delete mention rule - GET`/v1/outreach/queue`List outreach queue - GET`/v1/outreach/queue/stats`Get queue statistics - POST`/v1/outreach/queue`Add draft to queue - POST`/v1/outreach/queue/{id}/publish`Publish a draft - DELETE`/v1/outreach/queue/{id}`Delete a draft - GET`/v1/outreach/hn/search`Search Hacker News - GET`/v1/outreach/hn/trending`HN trending stories - GET`/v1/outreach/reddit/search`Search Reddit - POST`/v1/outreach/reddit/post`Post to Reddit - GET`/v1/outreach/reddit/status`Reddit connection status - POST`/v1/outreach/x/browse`Browse X/Twitter via CDP - POST`/v1/outreach/x/compose`Compose tweet - GET`/v1/outreach/memory`Get content memory state - GET`/v1/outreach/memory/history`Get post history ### System Actions macOS system automation (26 action domains, integrated) - GET`/v1/action-piper/status`System actions status - POST`/v1/action-piper/execute`Execute a system action - GET`/v1/action-piper/app/list`List running apps - GET`/v1/action-piper/app/snapshot`Native app AX snapshot - POST`/v1/action-piper/app/action`Perform native app action - POST`/v1/action-piper/app/assert`Assert native app state - GET`/v1/action-piper/window/list`List all windows - GET`/v1/action-piper/system`System info - GET`/v1/action-piper/system/{domain}`System info for specific domain ### API Connections Manage external API connections (OpenAI, Anthropic, Google, etc.) - GET`/connections`List API connections - POST`/connections`Create API connection - PUT`/connections/{id}`Update API connection - DELETE`/connections/{id}`Delete API connection ### Tool Permissions MCP tool access control - GET`/v1/tool-permissions`Get tool permission settings - PUT`/v1/tool-permissions`Update tool permissions ### Configurations Endpoint-level inference configurations - GET`/configurations`List all configurations - POST`/configurations`Create a configuration - PUT`/configurations/{id}`Update a configuration - DELETE`/configurations/{id}`Delete a configuration ### Recording Unified browser + native app recording - POST`/v1/record/start`Start unified recording session - POST`/v1/record/stop`Stop recording session - GET`/v1/record/stream`SSE stream of recorded actions ### Workflow Templates Curated pipeline workflow templates - GET`/workflow-templates`List available workflow templates ### System Health, resources, events, and logging - GET`/status`Health check (no auth) - GET`/system/resources`GPU, RAM, and ANE usage - GET`/events`SSE event stream - GET`/license`Subscription tier - GET`/v1/openapi.json`OpenAPI spec (no auth) - POST`/log`Post a single log entry (no auth) - GET`/logs`Query log entries (no auth) - POST`/logs`Post log entries in batch (no auth) - GET`/logs/stream`Real-time SSE log stream - POST`/clear`Clear all log entries - POST`/export`Export logs to file