Developer API

Last updated: July 7, 2026

Overview

The Maverick Developer API provides a comprehensive, local-only interface for programmatically controlling your Maverick device. Built on REST and WebSocket protocols, the API lets you create and manage agents, load and swap models, query device status, and build fully custom integrations — all without a single byte of data leaving your local network.

Because Maverick is designed around the principle of local-first intelligence, every API endpoint is reachable exclusively through your LAN. There are no cloud gateways, no external relay servers, and no third-party intermediaries. Your code talks directly to your Maverick, period. This makes the API ideal for building privacy-sensitive automations, on-premise dashboards, and self-hosted AI workflows that meet the strictest compliance requirements.

Getting Started

Setting up your development environment is straightforward. Follow these steps to start building with the Maverick API:

  1. Enable Developer Mode — Open the Maverick App, navigate to Settings > Advanced, and toggle on Developer Mode. You will be prompted to create an API key, which is stored securely on the device and never transmitted externally.
  2. Generate an API Key — Each API key is scoped with granular permissions (read, write, admin) and can be rotated or revoked at any time from the app or via the API itself. You can create multiple keys for different projects or team members.
  3. Connect to your Maverick — Once paired on the same network, your Maverick is accessible at http://maverick.local (or its LAN IP address). All API requests are made to this endpoint.
  4. Make your first request — Send a GET request to /api/v1/system/status with your API key in the X-Maverick-Key header to verify connectivity.

Endpoints

The API is organized into four logical resource groups, each serving a distinct domain of Maverick functionality:

Agents

  • GET /api/v1/agents — List all configured agents with their current status, resource usage, and assigned model.
  • POST /api/v1/agents — Create a new agent with a specified name, system prompt, model binding, and permission scope.
  • GET /api/v1/agents/:id — Retrieve detailed information about a specific agent, including its configuration, activity log, and performance metrics.
  • PUT /api/v1/agents/:id — Update an agent's configuration, such as its prompt, model, or permissions.
  • DELETE /api/v1/agents/:id — Remove an agent and free all associated resources.
  • POST /api/v1/agents/:id/invoke — Send a prompt or task to an agent and receive a streaming or synchronous response.

Models

  • GET /api/v1/models — List all models installed on the device, including size, format, and parameter count.
  • POST /api/v1/models/download — Initiate a model download from the Maverick model registry or a custom URL, with progress tracking via WebSocket.
  • DELETE /api/v1/models/:id — Uninstall a model and reclaim storage space on the device.

Devices

  • GET /api/v1/devices — List all smart home devices connected to and managed by your Maverick hub.
  • POST /api/v1/devices/:id/command — Send a control command (on/off, dim, lock, etc.) to a connected smart home device.
  • GET /api/v1/devices/:id/status — Retrieve the current state and sensor readings of a connected device.

System

  • GET /api/v1/system/status — Get device health, firmware version, uptime, temperature, CPU/GPU utilization, and available storage.
  • POST /api/v1/system/restart — Trigger a graceful device restart with optional agent preservation.
  • GET /api/v1/system/logs — Retrieve system and agent logs with filtering by severity, source, and time range.

Authentication

All API requests must include a valid API key in the X-Maverick-Key HTTP header. Keys are created and managed exclusively through the Maverick App or the /api/v1/system/keys endpoint. Each key is assigned one of three permission levels:

  • Read — Can query agent status, list models, and retrieve device information. Ideal for dashboards and monitoring tools.
  • Write — Includes all read permissions plus the ability to create agents, download models, and send device commands. Suitable for automation scripts and integrations.
  • Admin — Full access, including key management, system restart, firmware updates, and device factory reset. Reserve this for trusted infrastructure only.

Failed authentication returns a 401 Unauthorized response. Rate-limited or expired keys return 403 Forbidden with a descriptive error body.

SDKs

While you can interact with the API directly over HTTP, we provide official SDKs to accelerate your development:

  • Python SDK — A fully typed async/await SDK with first-class support for streaming responses, agent chaining, and model lifecycle management. Install via pip and start building in minutes.
  • JavaScript / TypeScript SDK — Available for both Node.js and browser environments, with WebSocket support built in. Ideal for building web dashboards, Electron apps, and server-side automation.
  • Swift SDK — Native iOS and macOS SDK for building Maverick integrations directly into Apple platform apps. Supports Combine-based reactive streaming and full async/await.

All SDKs are open-source, hosted on GitHub, and published to their respective package managers. Community-maintained SDKs for Rust and Go are also available in the Maverick GitHub organization.

Rate Limits

To ensure stable performance on the device, the API enforces the following rate limits per API key:

  • REST endpoints — 120 requests per minute per key. Burst allowance of up to 30 requests in a 5-second window.
  • WebSocket connections — Maximum of 10 concurrent connections per key. Each connection supports unlimited bidirectional messaging within the rate window.
  • Model downloads — 1 concurrent download per device. Additional download requests are queued automatically.

Rate limit headers (X-RateLimit-Remaining and X-RateLimit-Reset) are included in every response. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when to retry.

Documentation

The full API reference, including request/response schemas, error codes, WebSocket event types, and runnable code examples for every endpoint, is available in our interactive documentation. Access it locally by navigating to http://maverick.local/docs on any device connected to the same network as your Maverick.