API Circle Studio

An API workspace you can git diff.
A desktop, web, and VS Code workspace where collections live in your repo.
MCP and headless CLI automation have moved to API Circle Lens.

---

API Circle Studio is an API client in the spirit of Postman and Insomnia, rebuilt around two ideas the others miss:

1. Your workspace is a Git repo. Collections, environments, and mock definitions are plain JSON pushed to your own GitHub repo on a working branch. Teams collaborate the way they collaborate on code — branches, diffs, pull requests, review.
2. Your workspace stays portable. Studio writes .apicircle workspace files that API Circle Lens can open when you need MCP tools or headless CLI automation.

No cloud account. No vendor lock-in. Your data stays on your machine and in your repo.

---

Why API Circle Studio

• Own your data. The workspace is JSON you can read, diff, and back up. Secrets are encrypted locally (AES-GCM via WebCrypto, wrapped by the OS keychain on desktop). Nothing is uploaded to a third-party server.
• Collaborate through pull requests. Auto-create a working branch from main — starting from your own workspace, or importing one that already lives on the base branch — push to save, and open a PR from inside the app. API collections get the same review workflow as the code that calls them.
• Automation-ready. Studio keeps the workspace format clean and Git-backed; API Circle Lens now owns MCP and headless CLI automation on top of the same files.
• Runs where you work. Desktop, browser, VS Code, and embeddable npm packages share one engine and one workspace format. Lens-owned automation composes the same core when you need MCP or CLI workflows.
• Comfortable to tune. Settings ships 60+ themes (One Dark Pro is the default; dark, light, and high-contrast variants for VS Code, GitHub, Kanagawa, Everforest, Nightfox, Tokyo Night, Solarized, and more) and 50+ fonts (System Sans by default; full mono and sans families from Google Fonts plus a safe macOS system stack). Every theme also recolors the Monaco code editor. Click-open Theme and Font Family pickers, one-second hover previews with a pending indicator, keyboard previews, and UI text-size scaling round it out.
• Built on open standards. Git for sync, OpenAPI / Postman / Insomnia / HAR for import, and MCP through API Circle Lens. No proprietary formats waiting to trap you.

Features

Git-backed workspaces

A workspace is two JSON documents — workspace.json (the shared collection tree, environments, mocks) and workspace.local.json (per-device history, sessions, UI state). The synced document pushes to a GitHub repo on a working branch; teammates pull, branch, and merge it like any other file. Individual folders + environments can also be exchanged out-of-band as portable .apicircle.json exports — see Import what you already have below.

Lens-compatible MCP and CLI automation

MCP is deprecated in API Circle Studio. Studio no longer ships, publishes, configures, or documents an active MCP server or MCP CLI. Existing .apicircle workspaces remain compatible with API Circle Lens; open the same repo in Lens and use apicircle-lens mcp for supported AI-client workflows.

Local mock servers

Point API Circle at an OpenAPI, Swagger, Postman, or Insomnia file and get a running HTTP mock on localhost in seconds. The Hono-based engine handles $ref dereferencing, per-endpoint overrides (flip a 200 to a 503 to exercise error paths), conditional response rules, request validation, and response multipliers. Mock definitions live in the synced workspace so teammates share them; runtime state stays on the local machine.

A complete request toolkit

• 17 authentication schemes, all end-to-end functional — Bearer, Basic, API key, custom header, the full OAuth2 grant set (client credentials, auth code, PKCE, password, implicit, device flow, with auto-refresh), AWS SigV4, Digest, NTLM, Hawk, and JWT. Signing primitives are verified against the relevant RFC and NIST reference vectors. Folder-level auth is editable on every surface: set an auth: block on a folder and any descendant request with auth: { type: inherit } picks it up automatically. In VS Code, click a folder to open its YAML; a ◆ Inherits from <Folder> CodeLens on each inherit request links straight to the source.
• Import what you already have — cURL commands, OpenAPI/Swagger, Postman collections + environments, Insomnia exports, HAR files, and API Circle folder + environment exports (.apicircle.json produced by the folder kebab → Export as JSON, with embedded JSON Schema + GraphQL dependencies; the Environments sidebar's Export as JSON round-trips env vars including encrypted rows — the importer either matches an existing vault slot by label or pops a "Provide secret values" second step to bind them, skippable so the env is usable either way).
• Generate client code from any saved request — cURL, fetch, Node (axios), Python (requests), Go, and Rust.
• Environments with priority ordering and cross-workspace variable sources.
• Global Assets for reusable JSON Schemas, GraphQL definitions, and file assets. Request uploads, execution plans, and mock binary responses can all point at the same tracked asset metadata while file bytes travel as Git blobs alongside the synced doc, both under .apicircle/ in the repo (.apicircle/workspace-<id>/workspace.json plus .apicircle/workspace-<id>/attachments/<slotId>).
• Assertions and multi-step execution plans that chain requests.
• Request history with full headers, body previews, and assertion results.

Pick your surface

Surface	Best for
Desktop app	Day-to-day development (Windows / macOS / Linux)
Web app	Quick access, zero install
VS Code extension	Editing the same .apicircle/ workspace from your IDE — see below
API Circle Lens	MCP and headless CLI automation on the same .apicircle workspace
npm packages	Embedding the engine in your own tooling

VS Code extension (apps/vscode/)

Install: Visual Studio Marketplace · Open VSX — or search API Circle Studio in the Extensions view (Ctrl/Cmd+Shift+X).

The same workspace document the desktop and web apps drive can be edited in place from VS Code — no embedded webview, no separate sync. The extension contributes:

• Seven sidebar TreeViews: Workspace, Editor, Environment, Execution Plans, Mock servers, History, and Snapshots. The old MCP view was removed from Studio; use API Circle Lens for MCP setup.
• .req.yaml / .env.yaml / .run.yaml virtual documents under the apicircle: URI scheme — full Monaco editing with JSON Schema validation, completion for the 17 auth types + body types + assertion kinds, ▶ Send / Set Active / Delete CodeLenses, and live pre-send diagnostics in the Problems panel.
• Execution-plan editing — the plan YAML carries ▶ Run with assertions / ▶ Run (the app's two run modes; a running plan swaps to ⏳ Running… · ✖ Cancel), ◆ Plan environments…, and ✚ Add step… (a multi-select picker that hides already-added requests and offers "Select all"). Each step row is annotated with a # <name> · <METHOD> · <folder> comment, and the per-step actions — Open / Enable-Disable / Change / Remove — live on the Execution sidebar (single-click opens the request; inline buttons + the right-click menu). A plan run in History expands each step with full request + assertion detail.
• Three-surface byte-identical state with Desktop and Web — same applyMutation chokepoint, same workspace shape, byte-for-byte identical commits. One repo, three surfaces.
• Auto-refresh on external writes — file watchers on both the synced and device-local files so Lens-owned CLI/MCP changes or hand-edits propagate without manual refresh.
• Mock servers — spin up local HTTP mocks from OpenAPI / Postman / Insomnia specs, hit them with the request editor, and see request counts in the status bar.
• Secret vault (Phase 4) — passphrase-unlocked, in-memory AES-GCM key, auto-lock by inactivity, clipboard auto-clear on copy, reveal encrypted environment variables in place, consolidated APICircle Runs OutputChannel.
• MCP status — deprecated in Studio. Use API Circle Lens for MCP host integration, AI-client config snippets, Copilot/ChatGPT/Cursor setup, and current protocol validation.
• Wired settings for execution timeout, Remote-SSH host hint, history retention, and secret vault auto-lock + clipboard-clear.

First public Marketplace cut at 1.1.0; now 1.1.3, back in lockstep with the rest of the monorepo. Bundle currently 2.76 MB, well under the soft 3.0 MB / hard 5.0 MB budget defined in scripts/vscode-bundle-budget.mjs and enforced by scripts/check-vscode-bundle.mjs

• apps/vscode/test/integration/bundleSize.test.ts. E2E coverage in e2e/vscode/src/test/.

Two ways to use it

API Circle Studio runs in two modes. The workspace lives in different places in each. Pick the one that matches what you're doing.

Mode A — Local workspace (Desktop or Web app)

Open the app and a workspace is created automatically in browser storage (IndexedDB). No folder to manage, no flags to remember.

Everything works from inside the app:

• The Mocks panel starts and stops local mock servers from your OpenAPI, Postman, or Insomnia specs. The VS Code extension's Mock view ships the same lifecycle — start mocks from your IDE without switching apps.
• MCP setup is no longer provided by Studio. Open the same .apicircle workspace in API Circle Lens when you need AI-client config snippets or apicircle-lens mcp.

This is the easiest way to get started. You don't need a workspace folder, a git repo, or a --workspace flag.

Mode B — Git-backed workspace (teams, CI, headless tooling)

When you want to collaborate via PRs or later use Lens-owned CLI/MCP automation against JSON-on-disk, use the app's Link to Git feature to bridge your local workspace to a GitHub repo. The repo becomes your portable workspace.

Teammates get a usable workspace by cloning it:

git clone https://github.com/<you>/<your-workspace-repo>

The cloned directory is the workspace folder. It contains:

• workspace.json — collections, environments, mock definitions (shared with the team)
• workspace.local.json — per-device history, sessions, runtime state (kept out of git)

Open that folder in API Circle Lens when you need MCP or CLI automation:

apicircle-lens mcp --repo ./<your-workspace-repo>

Wherever the docs or a CLI flag say "workspace folder," they mean a directory shaped like a clone of an API Circle workspace repo. If you don't have one yet, start in mode A — that's how you create the workspace. "Link to Git" then turns it into a repo.

Quick start

Desktop app (mode A)

Grab the installer for your OS from the latest release, then follow the one-time setup step in docs/installing.md.

Headless automation

Studio no longer publishes the old @apicircle/cli or @apicircle/mcp-server packages. Use API Circle Lens for current CLI and MCP workflows:

apicircle-lens mcp --repo ./your-workspace-repo
apicircle-lens run "Smoke Tests" --repo ./your-workspace-repo

Run from source

Requires Node ≥ 20 and pnpm ≥ 9.

pnpm install
pnpm dev:web            # web app → http://localhost:5174

Connect your AI client

MCP has moved to API Circle Lens. Studio no longer ships, publishes, configures, or documents an active MCP server or MCP CLI. Existing Studio references to apicircle-mcp, @apicircle/mcp-server, or apicircle mcp are legacy/deprecated.

Open the same .apicircle workspace in Lens and use:

apicircle-lens mcp --repo ./your-workspace-repo

How it works

Every write to a workspace from Studio funnels through a single mutation API (applyMutation) in @apicircle/core. Lens-owned MCP and CLI automation compose the same core package boundary, so Studio workspaces remain compatible without Studio shipping those headless surfaces. See docs/architecture/platform.md for the current platform notes.

Project status

API Circle Studio is self-funded and actively developed in the open. Expect occasional rough edges as the 1.1.x line matures. The desktop builds are currently unsigned (code-signing certificates are not yet funded), so the first launch triggers a one-time OS security prompt — docs/installing.md walks through it. Builds are produced in the open by this repo's GitHub Actions. Issues and feedback are very welcome: github.com/apicircle/studio/issues.

Workspace storage layout

Every Git-backed workspace lives under a single .apicircle/ hidden directory. Since 1.1.0, each workspace gets its own per-id subdirectory, indexed by a registry.json:

your-repo/
└── .apicircle/
    ├── registry.json                      # workspace index
    └── workspace-<id>/
        ├── workspace.json                 # the synced workspace document
        └── attachments/<slotId>           # binary file attachments

This layout has gone through two hard cutovers:

• 1.0.9 moved workspace.json from the repo root into .apicircle/.
• 1.1.0 moved it again into per-id subdirectories (.apicircle/workspace-<id>/workspace.json) and added registry.json.

Neither old layout is read by current versions. If you have a repo on an older layout, the easiest fix is to re-push from the desktop app — it writes the current layout automatically. For manual migration steps or an export → re-import workflow, see docs/migration.md.

Documentation

• Connect your AI client
• Mock server guide
• MCP tool catalog reference
• Authentication — the 17-scheme matrix
• Platform architecture (MCP, mock engine, CLI, desktop)
• Installing the desktop app
• Migration guide — workspace storage relocation
• QA — coverage status and E2E CI

Repository layout

apps/
  web/                  Vite + React shell — the browser build
  desktop/              Electron shell — local mock bridges, OS-keychain secrets
packages/
  ui-components/        React UI + Zustand store + IndexedDB persistence
  core/                 Request execution, auth signing, assertions, mutation API
  shared/               Types, generateId, validators, encryption helpers
  git/                  GitHub API client + sync logic
  mock-server-core/     Hono mock-server engine + OpenAPI/Postman/Insomnia parsers

@apicircle/{shared,core,mock-server-core} are published to npm. MCP and CLI publishing moved to API Circle Lens; apps/*, git, and ui-components are workspace-private.

Develop

pnpm install            # install workspace deps
pnpm dev:web            # web dev server → http://localhost:5174
pnpm dev                # turbo dev (all apps)
pnpm build              # turbo build
pnpm check              # typecheck (tsc --noEmit per package)
pnpm lint               # eslint
pnpm test               # vitest unit tests
pnpm test:e2e           # Playwright E2E (web)
pnpm test:e2e:live-github # live api.github.com suite; requires bot PAT env

Desktop: pnpm --filter @apicircle/desktop build, then … start.

License

API Circle Studio is released under a custom source-available license — the source is open to read, study, and contribute to, but this is not an OSI-approved open-source license. It is free for personal, educational, and non-commercial use (plus a 30-day commercial evaluation period); ongoing commercial use requires a separate license. See LICENSE for the full terms, or contact apicircle365@gmail.com for commercial licensing.