{ "openapi": "3.1.0", "info": { "title": "Localisync Workspaces & Memberships", "version": "1.0.0", "description": "Same-origin session API. Secure deployments use __Host-localisync-session; explicitly configured local HTTP uses localisync-session. Membership and role authorization are checked on every request." }, "paths": { "/api/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List your workspaces", "description": "Lists only workspaces of which the signed-in customer is currently a member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePage" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWorkspace", "summary": "Create a workspace", "description": "Requires an invited, verified customer session. Creating a workspace assigns its single Owner; it grants no platform role.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Product team" } } } }, "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}": { "get": { "operationId": "getWorkspace", "summary": "Read a workspace", "description": "Requires current workspace membership. All workspace roles can read this resource, including when archived.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "renameWorkspace", "summary": "Rename a workspace", "description": "Requires current Owner/Admin membership and an active workspace.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "version", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/members": { "get": { "operationId": "listMembers", "summary": "List workspace members", "description": "Requires current workspace membership. All workspace roles can read this resource, including when archived.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberPage" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/members/{identityId}": { "patch": { "operationId": "changeMemberRole", "summary": "Change a non-owner role", "description": "Requires current Owner/Admin membership and an active workspace. Owner membership cannot be changed or removed through ordinary member endpoints.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "identityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "role": { "type": "string", "enum": [ "Admin", "Editor", "Viewer" ] } }, "required": [ "version", "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removeMember", "summary": "Remove a non-owner member", "description": "Requires current Owner/Admin membership and an active workspace. Owner membership cannot be changed or removed through ordinary member endpoints.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "identityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/leave": { "post": { "operationId": "leaveWorkspace", "summary": "Leave", "description": "Requires current non-owner membership. The Owner must transfer ownership first. Non-owners may leave an archived workspace; accounts and other memberships remain intact.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/archive": { "post": { "operationId": "archiveWorkspace", "summary": "Archive", "description": "Requires the workspace Owner. Transfer requires an existing member and makes the previous Owner an Admin. Workspace archival revokes pending invitations; restoration does not revive them.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/restore": { "post": { "operationId": "restoreWorkspace", "summary": "Restore", "description": "Requires the workspace Owner. Transfer requires an existing member and makes the previous Owner an Admin. Workspace archival revokes pending invitations; restoration does not revive them.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/transfer-ownership": { "post": { "operationId": "transferOwnership", "summary": "Transfer ownership", "description": "Requires the workspace Owner. Transfer requires an existing member and makes the previous Owner an Admin. Workspace archival revokes pending invitations; restoration does not revive them.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "identityId": { "type": "string", "format": "uuid" } }, "required": [ "version", "identityId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/invitations": { "get": { "operationId": "listWorkspaceInvitations", "summary": "List workspace invitations", "description": "Requires current workspace membership. Only Owner/Admin can list workspace invitations.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationPage" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createInvitation", "summary": "Create and send an invitation", "description": "Requires current Owner/Admin membership and an active workspace.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "role": { "type": "string", "enum": [ "Admin", "Editor", "Viewer" ] } }, "required": [ "version", "email", "role" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Completed. For invitation creation/resend, inspect delivery; accepted means SMTP accepted the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/invitations/{invitationId}/resend": { "post": { "operationId": "resendInvitation", "summary": "Resend invitation", "description": "Requires current Owner/Admin membership and an active workspace.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Completed. For invitation creation/resend, inspect delivery; accepted means SMTP accepted the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{id}/invitations/{invitationId}/revoke": { "post": { "operationId": "revokeInvitation", "summary": "Revoke invitation", "description": "Requires current Owner/Admin membership and an active workspace.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/invitations": { "get": { "operationId": "listMyInvitations", "summary": "List your invitations", "description": "Available only to the invitation recipient signed into the bound account. Acceptance checks expiry, current invitation state and workspace state; a link alone grants no membership.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationPage" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/invitations/{id}": { "get": { "operationId": "getMyInvitation", "summary": "Read your invitation", "description": "Available only to the invitation recipient signed into the bound account. Acceptance checks expiry, current invitation state and workspace state; a link alone grants no membership.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/invitations/{id}/accept": { "post": { "operationId": "acceptInvitation", "summary": "Accept your invitation", "description": "Available only to the invitation recipient signed into the bound account. Acceptance checks expiry, current invitation state and workspace state; a link alone grants no membership.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponse" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/invitations/{id}/decline": { "post": { "operationId": "declineInvitation", "summary": "Decline your invitation", "description": "Available only to the invitation recipient signed into the bound account. Acceptance checks expiry, current invitation state and workspace state; a link alone grants no membership.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "responses": { "201": { "description": "Completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponse" } } } }, "400": { "description": "Invalid request fields, identifier, pagination or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "An authenticated, verified customer session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The current member lacks permission or CSRF/Origin validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or not visible to the current customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, conflicting idempotency key or unavailable invitation/workspace state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or invitation send limit reached. Respect Retry-After in seconds; route limits return the remaining window, invitation limits return 60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required database, identity or email service is unavailable; no successful send is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "ownerIdentityId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "role": { "type": "string", "enum": [ "Owner", "Admin", "Editor", "Viewer" ] } }, "required": [ "id", "name", "ownerIdentityId", "version", "archivedAt", "createdAt", "role" ], "additionalProperties": false }, "Member": { "type": "object", "properties": { "identityId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "Owner", "Admin", "Editor", "Viewer" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "identityId", "email", "role", "createdAt" ], "additionalProperties": false }, "Invitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "workspaceName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "Admin", "Editor", "Viewer" ] }, "inviterId": { "type": "string", "format": "uuid" }, "recipientId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "delivery": { "type": "string", "enum": [ "preparing", "accepted", "unconfirmed" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "workspaceName", "email", "role", "inviterId", "recipientId", "status", "delivery", "expiresAt", "createdAt" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, "Success": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false }, "InvitationResponse": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "WorkspacePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ], "additionalProperties": false }, "MemberPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ], "additionalProperties": false }, "InvitationPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ], "additionalProperties": false } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-localisync-session" } } } }