Skill: Workspace Management

Description

Manage workspaces. This skill documents the public API at

/api/v2/workspaces

X-API-KEY

page

page_size

page_size

page=0

TypeScript types (request / response)

Mirrors

PublicApiWorkspaceController

// --- Create (POST) — 201 ---
type PublicApiCreateWorkspaceRequest = {
  name: string;           // required, 1–255 chars
  description?: string | null;
  default_theme_id?: string | null;  // optional theme UUID
};
type PublicApiWorkspaceResponse = {
  id: string;
  user_id: string;
  name: string;
  description: string | null;
  default_theme_id: string | null;
  shared_working_dir_live_object_id: string;
  project_count: number;
  created_at: string;     // ISO 8601
  updated_at: string;    // ISO 8601
  thumbnail_url?: string | null;
};

// --- List (GET) ---
// Query: page (use 0 for first page), page_size (default 20, max 100)
type PublicApiWorkspaceListResponse = {
  data: PublicApiWorkspaceResponse[];
  total: number;
  page: number;
  page_size: number;
};

// --- Restore (POST /{workspace_id}/restore) ---
type PublicApiRestoreWorkspaceRequest = {
  restore_projects?: boolean;  // default true
};
type PublicApiRestoreWorkspaceResponse = {
  workspace_restored: boolean;
  projects_restored: number;
};

// --- List files (GET /{workspace_id}/files) ---
// Optional query: type (file classification filter, if supported by server)
type PublicApiWorkspaceFileEntry = {
  id: string;
  name: string;
  path: string;
  file_type: string;
  mime_type: string;
  size: number;
  uploaded_at: string;
  uploaded_by: string;
  status: string;
  presigned_url?: string | null;
  url_expires_at?: string | null;
};
type PublicApiWorkspaceFilesResponse = {
  files: PublicApiWorkspaceFileEntry[];
  total: number;
};

// --- Update (PUT) ---
type PublicApiUpdateWorkspaceRequest = {
  name?: string | null;   // max 255 if provided
  description?: string | null;
  default_theme_id?: string | null;  // optional theme UUID
};

Create Workspace

Request body:

PublicApiCreateWorkspaceRequest

PublicApiWorkspaceResponse

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/workspaces" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"name":"<workspace_name>","description":"<description>"}'

List Workspaces

Query:

page

0

page_size

PublicApiWorkspaceListResponse

curl "$LAYERPROOF_BASE_URL/api/v2/workspaces?page=0&page_size=20" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

List Deleted Workspaces

Soft-deleted workspaces for the current user. Query:

page

page_size

curl "$LAYERPROOF_BASE_URL/api/v2/workspaces/deleted?page=0&page_size=20" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Restore Workspace

Body optional:

{"restore_projects": true}

PublicApiRestoreWorkspaceResponse

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/workspaces/<workspace_id>/restore" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"restore_projects":true}'

Permanently Delete Workspace

Hard-deletes a workspace that is already soft-deleted. Response: 204 No Content.

curl -X DELETE "$LAYERPROOF_BASE_URL/api/v2/workspaces/<workspace_id>/permanently" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

List Files in Workspace

Lists files in the workspace shared working directory. Optional query:

type

curl "$LAYERPROOF_BASE_URL/api/v2/workspaces/<workspace_id>/files" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Get Workspace

Response:

PublicApiWorkspaceResponse

curl "$LAYERPROOF_BASE_URL/api/v2/workspaces/<workspace_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Update Workspace

Request body:

PublicApiUpdateWorkspaceRequest

PublicApiWorkspaceResponse

curl -X PUT "$LAYERPROOF_BASE_URL/api/v2/workspaces/<workspace_id>" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"name":"New name","description":"New description"}'

Delete Workspace

Response: 204 No Content.

curl -X DELETE "$LAYERPROOF_BASE_URL/api/v2/workspaces/<workspace_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Agent behavior

When the user asks to manage workspaces (create, list, get, update, delete), do the following.

1. Choose the right endpoint

/api/v2/workspaces

/api/v2/workspaces?page=0&page_size=20

/api/v2/workspaces/deleted?page=0&page_size=20

/api/v2/workspaces/{workspaceId}/restore

/api/v2/workspaces/{workspaceId}/permanently

/api/v2/workspaces/{workspaceId}/files

/api/v2/workspaces/{workspaceId}

/api/v2/workspaces/{workspaceId}

/api/v2/workspaces/{workspaceId}

2. Build and run

Step 1 — Check environment variables first. Before running any curl command, verify both

LAYERPROOF_BASE_URL

LAYERPROOF_API_KEY

if [[ -z "${LAYERPROOF_BASE_URL}" ]]; then
  echo "ERROR: LAYERPROOF_BASE_URL is not set."
  return 1
fi
if [[ -z "${LAYERPROOF_API_KEY}" ]]; then
  echo "ERROR: LAYERPROOF_API_KEY is not set."
  return 1
fi

If running from a project directory with a

.env.local

if [[ -f .env.local ]]; then
  set -a
  source .env.local
  set +a
fi

Step 2 — Auth: Include

X-API-KEY: $LAYERPROOF_API_KEY

LAYERPROOF_BASE_URL

LAYERPROOF_API_KEY

Step 3 — GET: Build path and query params (

page

page_size

Step 4 — POST/PUT: Build JSON body (name, description for create; name/description optional for update). Run curl and show result.

Step 5 — DELETE: Build path; run curl. Response is 204 with no body.

3. Response handling

• Always show the raw JSON response in a JSON code block.
• For 204 delete, indicate success and no body.
• On error, show response body and status code.

4. Example workflows

Workflow A — User: "Create workspace Marketing."

1. Choose POST /api/v2/workspaces.
2. Body:

   {"name":"Marketing"}

   (or with description).
3. Run curl; show JSON. Returned

   id

   is the workspace ID for get/update/delete.

Workflow B — User: "Set up a workspace for Q2, create it if it doesn’t exist, then list my workspaces and show the one I’ll use for new projects."

1. GET

   /api/v2/workspaces

   with

   page

   ,

   page_size

   ; inspect list for a workspace named "Q2" or similar.
2. If not found: POST

   /api/v2/workspaces

   with

   {"name":"Q2","description":"Q2 campaigns and decks"}

   ; capture

   id

   as

   workspace_id

   .
3. If found: use that workspace’s

   id

   . Optionally GET

   /api/v2/workspaces/{id}

   to show full details.
4. Tell user: "Use workspace_id <id> when creating projects (e.g. POST /api/v2/projects with workspace_id in body)."

Workflow C — User: "Rename workspace X to 'Marketing 2025' and add a description."

1. Resolve workspace ID (from list or user). PUT

   /api/v2/workspaces/{workspaceId}

   with

   {"name":"Marketing 2025","description":"..."}

   .
2. Run curl; show JSON. Optionally GET the workspace again to confirm name and description.

Response format (required)

• (if response contains url to show image) please show image and show json response instead of table
• Always show the raw JSON response (verbatim) in a JSON code block.
• If the response contains a URL for an image, render/show the image and also show the JSON response (do not convert to a table).