Switchy
Sign up
Guide

Migrating from v1

v2.0.0 is the team-workspace rebuild. Solo data carries forward untouched; the surface around it changed in a few specific places. This page covers what moved and what to do about it.

The headline change

v1 Switchy was a multi-model chat with private memory. v2 is a shared workspace where teammates, models, and MCP tools all chat in the same room. If you were using v1 alone, nothing in your chats or memory has been deleted; what used to be your account is now your org, and your existing chats live inside one starter Project.

Account → Org

  • Your user record is unchanged. You still log in with the same email + password (or Google).
  • An organization named after you was created the first time you logged in to v2. You are its OWNER.
  • Your existing sessions were moved into a Project called General inside that org. Conversation history, memory, attachments - all still there.

Memory: now has visibility

v1 memory was implicitly "mine." v2 memory has three visibilities:

  • PRIVATE - only you can read it.
  • PROJECT - anyone in the Project can read it.
  • ORG - anyone in the org can read it.

Every memory imported from v1 was set to PRIVATE. If you want a piece of context to be teammate-visible, edit it in Settings → Memory and bump the visibility. Retrieval enforces the same rules at the SQL layer, so you can't accidentally surface a private note in a teammate's search.

Billing: now org-scoped

v1 credits were per-user. v2 credits always live on an organization — on Starter and Pro that's your personal workspace, on Team it's the shared org pool. If you were on the v1 Pro plan:

  • You were re-mapped to the v2 Pro plan at the same price.
  • Your v1 credit balance was carried over as a one-time top-up that never expires.
  • If you upgrade to Team, the same balance moves to the org pool on the same terms.

Full mechanics: Team billing guide.

SDK: use 0.4.0 with an API key

The first SDKs (@switchy-ai/sdk@0.1.x, switchy-sdk@0.1.x) had a flat surface - client.chat(), client.memory.search(), etc. 0.3.x replaced it with org-scoped namespaces: spaces, sessions, messages, memory, members, invitations, billing. Those called the v2 endpoints, which accept only a signed-in session, so a script using an API key got 401 from every one of them.

@switchy-ai/sdk@0.4.0 (npm) and switchy-sdk==0.4.0 (PyPI) call the v1 API instead, authenticated with an sk_live_… key. The REST surface is client.memory. The 0.3.x namespaces that could never authenticate with a key are gone:

import { Switchy } from '@switchy-ai/sdk';

const client = new Switchy({ apiKey: process.env.SWITCHY_API_KEY! }); // sk_live_…

const memory = await client.memory.create({
  content: 'Deploys go out on Thursdays.',
  type: 'FACT',
  visibility: 'ORG',
});
const hits = await client.memory.search({ query: 'deploys' });
const { memories, total } = await client.memory.list({ limit: 20 });
await client.memory.delete(memory.id);

To read Projects and sessions or post messages from code, use the SDK's McpClient with an MCP key (listSpaces, listSessions, getSessionTranscript, postMessage). Each SDK's README has the side-by-side 0.3 → 0.4 table, and its CHANGELOG lists everything that was removed.

API: keys are for v1

The v2 API adds /spaces, /sessions, /messages, /invitations, /members endpoints and reorganises memory under /memory with a visibility filter. These are the session-authenticated endpoints the web app uses: they take the cookie you get by signing in, and API keys do not work on them. A request that carries only a key gets 401. The OpenAPI 3.1 spec is at /api/openapi.json and rendered at API reference.

API keys authenticate the v1 API under /api/v1 (spec at /api/v1/openapi.json). Use it for scripts and integrations.

MCP: now bidirectional

v1 only let you talk TO the AI. v2 lets the AI talk to your tools (GitHub, Notion, custom HTTPS MCPs) and lets your client (Claude Desktop, Cursor) talk to Switchy.

What broke

Two things from v1 are gone:

  • Per-user "default model" - replaced by the Project's default model + per-message @mention. Model preferences from v1 became Project defaults on the General Project.
  • The v1 dashboard /docs page - replaced by these public docs. Old in-app deep links auto-redirect.

Questions

If something carried over wrong, get in touch with your v1 user ID - the migration job logs every step and we can replay individual records.

←PreviousTeam billingNextAPI overview→