---
title: "Move a diagram into a team workspace"
method: POST
path: "/v1/diagrams/{id}/move"
tags: ["Diagrams"]
---

# Move a diagram into a team workspace

`POST /v1/diagrams/{id}/move`

## Request

- Base URL: `https://api.zindex.ai`
- URL: `https://api.zindex.ai/v1/diagrams/{id}/move`
- Auth: API key in cookie `zindex_session`

Moves one diagram from your personal workspace into a team workspace where you are an owner or member. It keeps its ID, every version and its hash chain. For the signed-in dashboard only, with the personal workspace selected: a key or connected app gets 403 SESSION_REQUIRED. Moving goes one way, personal to team.

## Path parameters

- `id` string, required

## Request body

- object
  - `workspaceId` string, required: The team workspace to move it to

## Response `200`

Moved: { id, key, workspace: { id, name } }

- object
  - `id` string, required
  - `key` string, nullable, required
  - `workspace` object, required
    - `id` string, required
    - `name` string, required

## Other responses

- `400`: INVALID_REQUEST: workspaceId isn't a team workspace you're in, or is the diagram's own
- `401`: Missing or invalid API key. Response includes a `code` field that distinguishes the failure mode so clients (dashboard, MCP server) can render actionable copy: `AUTH_REQUIRED` (no key or session was sent), `API_KEY_INVALID` (key not found), `API_KEY_REVOKED` (key was revoked, or its person is no longer in its workspace), `API_KEY_EXPIRED` (key passed its expires_at), and for the site's session cookie `SESSION_EXPIRED` (past its 24 hours), `SESSION_REVOKED` (the account's sessions were ended, for example by a password reset) and `SESSION_INVALID` (not a session this server signed).
- `403`: SESSION_REQUIRED: sent with a key or connected app; READ_ONLY: you're a viewer in the team; SHARING_DISABLED: the team's owners turned off public sharing and the diagram is public or has share links, so make it private and revoke its links first; LIMIT_REACHED: the team is at its diagram limit (scenes). Nothing moved
- `404`: NOT_FOUND
- `409`: KEY_EXISTS: the team already has a diagram with this key. Nothing moved
- `429`: RATE_LIMITED: over the request rate limit (see Rate Limiting). Wait retryAfter seconds (also the Retry-After header), then try again.

## Changes

- **2026-10-20** `1d21bd5bbf8e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zindex/apis/zindex-api/changes/v1/diagrams/:id/move/post.md)

---

[API](https://skmtc.dev/zindex/apis/zindex-api.md) · [All operations](https://skmtc.dev/zindex/apis/zindex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zindex/apis/zindex-api/revisions/1d21bd5bbf8e?raw)