Workspaces

Every diagram belongs to one workspace. Each person has a personal workspace and can also belong to team workspaces, as an owner, a member or a viewer. Every API key, connected app and dashboard session acts in exactly one workspace and sees only that workspace’s diagrams.

Team workspaces are a beta, open to every account. They are billed from the start: Team costs $8 per paid seat a month or $80 a year, with at least 2 seats, and viewers and agents are free. Team’s features, and the management endpoints below, may change during the beta; the diagram API and MCP tools don’t change with them. GET /v1/auth/me says whether the account can create a team workspace, in features.teams.

One workspace per credential

• An API key acts in the workspace it was made in: the one selected in the dashboard, or the workspace of the key that made it. A connected app acts in the workspace chosen when it was allowed. The dashboard acts in the workspace selected in its switcher.
• No endpoint or tool takes a workspace parameter. To work in two workspaces, use a key or a connection for each. Connecting the same app again in the same workspace replaces its earlier connection there; its connections to your other workspaces stay.
• A diagram in another workspace answers NOT_FOUND, as one that doesn’t exist does. Only in the dashboard does the answer name the other workspace, when you belong to it (workspace: { id, name } beside error and code), so you can switch to it.
• Keys are unique per workspace, so the same key can name one diagram in your personal workspace and another in a team workspace. Repeating your own create with the same key and content returns the existing diagram; a teammate’s create with a key the workspace already has answers 409 KEY_EXISTS, so read and edit that diagram instead.
• Everyone in a team workspace can read every diagram in it. There is no per-diagram privacy inside a workspace: draft in your personal workspace and move the diagram in when it is ready.

Roles

A team workspace can have several owners and always has at least one: removing, demoting or leaving as the last owner answers 409 LAST_OWNER. You are the owner of your personal workspace; the team-only actions answer 400 NOT_A_TEAM_WORKSPACE there.

Agents can’t manage a workspace. Inviting people, roles, domains, the sharing switch, moving a diagram and billing work only from the signed-in dashboard: an API key gets 403 SESSION_REQUIRED, and a connected app’s sign-in works only on /mcp.

Write and read access

Each API key and connected app has write or read access. What it may do is that access narrowed by its person’s role: a viewer’s write key acts read-only, and writes again if they become a member.

• Read access finds, reads (outline, scene JSON or Mermaid), renders, reads history and compares diagrams, downloads one diagram’s history, lists recently deleted diagrams, and sends feedback without a diagram. Anything that changes or shares a diagram, or reports a problem with one, answers 403 READ_ONLY, with reason: credential for a read key or app, role for a viewer. Over MCP the tool list is the same, and diagram_delete and diagram_share answer READ_ONLY before asking the person to confirm.
• Keys. POST /v1/auth/keys takes scope, write or read, defaulting to write when the caller can write and read otherwise. Asking for write without write access answers 403 READ_ONLY. A key made with a key gets that key’s workspace and a scope no wider than its own. A viewer can hold 3 keys in a workspace (403 PLAN_LIMIT_EXCEEDED with maximumAllowed: 3); viewers’ keys don’t count toward the workspace’s apiKeys limit. GET /v1/billing/me gives the cap as limits.viewerApiKeys, and a viewer the keys they hold as inventory.viewerApiKeys.
• Connected apps. A client that asks for the OAuth scope diagrams:read alone gets read access; diagrams, or no scope, asks for write. On the consent page the person chooses the workspace and the access. A viewer, or a client that asked only for diagrams:read, gets read whatever is chosen.
• History names people, not keys. Each version records who saved it, by (their name, else their email), and how, credential (session, api_key or oauth), but never which key (diagram_history).

Joining a team workspace

An owner adds people in three ways. Each one needs the workspace to be on Team, by a subscription or a plan Zindex provides (409 SUBSCRIPTION_REQUIRED otherwise), and a workspace holds at most 1,000 people (409 WORKSPACE_FULL). Joining needs a signed-in account with a verified email.

• Email invitation. An owner invites an address as a member or a viewer. The invitation works for 7 days, and only for an account whose verified email is that address (403 INVITATION_EMAIL_MISMATCH otherwise). A member is a paid seat, charged when the invitation is accepted; if the subscription has lapsed by then, or the seat can’t be added, the person joins as a viewer and the answer carries a note. Inviting the same address again sends a new link and stops the old one. An address that can’t have an account, such as a disposable inbox, can’t be invited unless it already has one, since nobody can sign up there to accept (400 EMAIL_NOT_ALLOWED). A workspace can send 50 invitations a day.
• Invite link. An owner makes one link for the workspace, shown once. Anyone who opens it joins with the link’s role. Making a new link stops the old one, and owners can turn it off.
• Email domain. An owner lists a domain such as acme.com, and people with a verified address there can join with the domain’s role: at once (auto), or when an owner approves (approval, the default, which emails every owner, saying what approving the person as a member would cost), and the approving owner can choose the other role. Domain join has the rules.

The invite link and each domain have a role, viewer (the default) or member, which owners can change at any time. Changing the link’s role keeps the same link.

• A viewer is free. An owner can make them a member later, which adds a paid seat.
• A member is a paid seat, charged when they join, as for an invitation. If the seat can’t be added, they join as a viewer, and the answer carries a note. When someone joins as a member by themselves, with the link or by a domain on auto, every owner gets an email naming them and the seat. A workspace on a plan Zindex provides (workspace.complimentary in GET /v1/billing/me) has no Stripe subscription: it is charged nothing, and no email is sent.
• Approving a request takes a role, which defaults to the domain’s.

Domain join

• A person qualifies when their account’s verified address is at exactly the listed domain. An address verified with a code sent to it, or through GitHub, qualifies. An address that came from Google sign-in qualifies only when Google reports the company’s Google Workspace domain (hd) for that account and it matches the listed domain. A personal Google account doesn’t, and the answer is 403 NOT_ELIGIBLE with reason: "google_hd": sign in with the company’s Google Workspace account, or ask an owner for an invitation.
• Public mail domains, such as gmail.com or outlook.com, can’t be listed (400 PUBLIC_MAIL_DOMAIN). Invite those people by email. Disposable inboxes can’t be listed either, and their addresses can’t have an account.
• An owner or member of the workspace must qualify for a domain before it can be listed (403 DOMAIN_NOT_HELD).
• Signing up or signing in never joins anyone. The dashboard offers the workspaces you can join; GET /v1/join/available lists them. Joining another way, by invitation or link, settles a pending request.
• Anyone who still has a verified address at the domain qualifies, including someone who has left the company. With approval, an owner checks each request.

Moving a diagram in

POST /v1/diagrams/{id}/move with { "workspaceId": "..." } 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. A published diagram stays published and its share links keep working, so everyone in the team, and anyone with a link, can still see it.

• It goes one way, personal to team, one diagram at a time. Nothing moves a diagram out of a team workspace.
• It works only from the signed-in dashboard with your personal workspace selected. A key or connected app gets 403 SESSION_REQUIRED.
• Afterwards your personal workspace’s keys and connected apps get NOT_FOUND for the diagram; the team’s see it.
• Nothing moves when the team already has a diagram with the same key (409 KEY_EXISTS; a key can’t be renamed, so delete one of the two), when the team’s sharing is off and the diagram is public or has share links (403 SHARING_DISABLED; make it private and revoke its links first), when the team is at its diagram limit (403 LIMIT_REACHED), or when you are a viewer there (403 READ_ONLY).

Public sharing

A team workspace’s owners can turn public sharing off. While it is off, publishing a diagram and creating a share link answer 403 SHARING_DISABLED, over REST and MCP; making a diagram private and revoking links still work.

• Turning sharing off doesn’t take down anything already shared. Make all private unpublishes every diagram and revokes every share link in the workspace; it doesn’t turn sharing off.
• Share links stay anonymous: anyone who has one sees the images. No link opens for workspace members only.
• The switch doesn’t cover render links. diagram_render and GET /v1/diagrams/{id}/render still return signed image links that anyone holding them can open for 7 days, and anyone in the workspace, viewers and read keys included, can make them.
• Each share link records who made it: createdBy in GET /v1/diagrams/{id}/links.

Seats, billing and limits

A team workspace is on Team or on Free (Limits). Team costs $8 a month or $80 a year for each paid seat.

• Each owner and member is a paid seat, with at least 2 per workspace. Viewers are free, and so are agents: a key or connected app acts as its person and costs nothing extra.
• Adding a seat is charged at once for the rest of the billing period. Removing one leaves a credit for the workspace’s later invoices, which isn’t paid out in cash. Seats follow roles; the billing portal doesn’t change them.
• Any owner can subscribe, open the billing portal and cancel. Pro is for a personal workspace and Team for a team one; checkout for the other answers 400 PLAN_NOT_AVAILABLE.
• The owner who completes checkout pays. If you paid for a team workspace and stop being an owner (you leave, are removed, are made a member or a viewer, transfer ownership, or close your account), your card is removed from it and its billing contact moves to a remaining owner, the one who joined first; invoices already issued keep the details they were issued with. Every card on the workspace goes, including one another owner added; that owner adds it again. The confirmation says so before you act.
• Every remaining owner then gets an email asking them to add a card before the subscription renews, and Billing shows them “No card on file” with Add a card, which opens the billing portal. While the subscription is set to cancel, the email asks them to resume it and add a card, and Billing shows Resume first. Until a card is added, a seat added is charged with the renewal instead of at once. Once a card is there, Zindex sees it the next time an owner opens Billing or another signed-in page; the owner who last opened the portal then pays, or the owner whose visit found it if that owner is no longer an owner or nobody opened it. If no card is added, the renewal payment fails and the subscription is past due. A plan Zindex provides has no subscription and no card, so none of this applies.
• Limits are pooled: Team gives Pro’s diagrams, updates, renders and keys for each paid seat, shared by everyone in the workspace, so one busy agent can use up the month’s updates for everyone. The rate limit is per person in each workspace.
• When the subscription ends, the workspace has Free’s limits. Everyone keeps their role. Until it is subscribed again, nobody new joins by link or domain and no invitation can be sent; an invitation sent before it ended can still be accepted, as a viewer.
• Each person who joins as a member, by the invite link, a domain or an approval, adds a paid seat (Joining a team workspace).
• You can have one team workspace you created that isn’t paid for; creating another answers 409 UNPAID_WORKSPACE_EXISTS.

GET /v1/billing/me returns the selected workspace’s plan, pooled usage, limits and seats (paid, billed, minimum) to anyone in it, and its Stripe state to owners only, including workspace.subscriptionInterval (month or year; null without a subscription, or until Stripe has said) and, for a team workspace, workspace.paidBy (the owner who pays, or null while nobody does) and workspace.paymentMethodNeeded: { since, renewsAt } while it needs a card because its payer stopped being an owner, else null (renewsAt is null until Stripe has said). workspace.complimentary, for anyone in it, is true on a paid plan Zindex provides, with no subscription and no charge for seats.

Leaving, deleting and exporting

• Leaving. Leave, or be removed by an owner: your keys and connected apps for that workspace are revoked, and the diagrams you made stay. The last owner can’t leave (409 LAST_OWNER); make someone else an owner first.
• Transfer. An owner makes someone else an owner and becomes a member or a viewer, or leaves.
• Deleting a team workspace. An owner types its name, then confirms from an email. Its diagrams with every version, its keys, connected apps, invitations and share links are deleted at once; its subscription is canceled with no refund for the rest of the period; everyone in it gets an email.
• Closing your account is refused while you are the last owner of a team workspace with other people in it (409 LAST_OWNER, listing them). A team workspace you are alone in is deleted with your account. In the others, the diagrams you made stay, and their history shows "former member". A team workspace you pay for keeps its subscription without your card (Seats, billing and limits).
• Export. GET /v1/workspace/export downloads every diagram in the workspace the request acts in (Export). In a team workspace only owners can, with a session or their own key (403 OWNER_REQUIRED otherwise); everyone can download one diagram’s history.

Management endpoints

The dashboard calls these with its signed-in session, except the routes that take an emailed or linked token instead (the previews, accepting a link and confirming a deletion). They aren’t in the OpenAPI spec, and an API key gets 403 SESSION_REQUIRED. They take and return JSON. Errors from the routes in these tables are { error, code }, with details for some codes. A 404 NOT_FOUND carries reason: workspace when you aren’t in the workspace (the one in the path, or workspaceId in a join), or it doesn’t exist; otherwise what is gone, member, invitation, invite_link, domain, join_request, key or app.

Workspaces and people

A workspace is { id, name, kind, role, plan, publicSharingDisabled, createdAt, people: { owners, members, viewers }, seats, subscriptionActive }, where seats is { paid, billed, minimum } for a team workspace and null for a personal one. A member is { userId, name, email, role, joinedVia, joinedAt, invitedBy, you, paysForWorkspace }. invitedBy, and addedBy on a domain, are { userId, name } (the person’s name, else their email), or null once that person has closed their account. GET /v1/auth/me adds workspace (the one the session acts in), workspaces (every one you are in, personal first) and features.teams.

A role change or transfer that adds a seat changes nothing and answers 502 BILLING_UNAVAILABLE when the subscription can’t be updated; try again in a minute.

Invitations and the invite link

Accepting when you are already in the workspace answers 409 ALREADY_MEMBER with workspace.

Domains and join requests

Everyone’s keys and apps, and sharing

The person whose key or app an owner revokes isn’t told. Everyone manages their own keys with POST /v1/auth/keys and DELETE /v1/auth/keys/{id}, and their own connected apps in the dashboard. The sharing endpoints are for team workspaces only.

Errors