Skip to main content
Workspaces organize teams, environments, and designs in Meshery. They provide logical isolation for multi-tenant deployments.

​
List Workspaces

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/workspaces?orgID=YOUR_ORG_ID&page=0&pagesize=25"
Method: GET Endpoint: /api/workspaces

​
Query Parameters

​
orgID
string
required
Organization ID to retrieve workspaces for (required for remote providers)
​
page
integer
default:"0"
Page number for pagination (0-indexed)
​
pagesize
integer
default:"20"
Number of workspaces per page
​
search
string
Search term for filtering workspaces by name
​
order
string
Field to order by (e.g., name, created_at, updated_at)
​
filter
string
JSON filter conditions

​
Response

​
page
integer
Current page number
​
page_size
integer
Number of items per page
​
total_count
integer
Total number of workspaces
​
workspaces
array
Array of workspace objects
Example Response: 
{
  "page": 0,
  "page_size": 25,
  "total_count": 3,
  "workspaces": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "description": "Production workloads",
      "organization_id": "org-123",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-20T14:45:00Z",
      "owner": "user-uuid"
    }
  ]
}

​
Get Workspace by ID

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/workspaces/{id}?orgID=YOUR_ORG_ID"
Method: GET Endpoint: /api/workspaces/{id}

​
Path Parameters

​
id
string
required
Workspace ID (UUID)

​
Query Parameters

​
orgID
string
Organization ID (required for remote providers)

​
Response

Returns a single workspace object with the same structure as the list response.

​
Create Workspace

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development",
    "description": "Development environment",
    "organization_id": "org-123"
  }' \
  http://localhost:9081/api/workspaces
Method: POST Endpoint: /api/workspaces

​
Request Body

​
name
string
required
Workspace name
​
description
string
Workspace description
​
organization_id
string
required
Organization ID that will own this workspace

​
Response

Status: 201 Created Returns the created workspace object.

​
Update Workspace

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Updated",
    "description": "Updated production workspace"
  }' \
  http://localhost:9081/api/workspaces/{id}
Method: PUT Endpoint: /api/workspaces/{id}

​
Path Parameters

​
id
string
required
Workspace ID (UUID)

​
Request Body

​
name
string
Updated workspace name
​
description
string
Updated workspace description

​
Response

Status: 200 OK Returns the updated workspace object.

​
Delete Workspace

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/workspaces/{id}
Method: DELETE Endpoint: /api/workspaces/{id}

​
Path Parameters

​
id
string
required
Workspace ID (UUID)

​
Response

Status: 200 OK Returns the deleted workspace object.

​
Get Workspace Environments

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/workspaces/{id}/environments?orgID=YOUR_ORG_ID&page=0&pagesize=25"
Method: GET Endpoint: /api/workspaces/{id}/environments

​
Path Parameters

​
id
string
required
Workspace ID (UUID)

​
Query Parameters

​
orgID
string
required
Organization ID
​
page
integer
default:"0"
Page number
​
pagesize
integer
default:"20"
Page size
​
search
string
Search term
​
order
string
Order by field
​
filter
string
Filter conditions: {"assigned": true/false, "deleted_at": true/false}

​
Response

Returns a paginated list of environments assigned to this workspace.

​
Add Environment to Workspace

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/workspaces/{id}/environments/{environmentID}
Method: POST Endpoint: /api/workspaces/{id}/environments/{environmentID}

​
Path Parameters

​
id
string
required
Workspace ID (UUID)
​
environmentID
string
required
Environment ID to add (UUID)

​
Response

Status: 201 Created Returns the workspace-environment mapping object.

​
Remove Environment from Workspace

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/workspaces/{id}/environments/{environmentID}
Method: DELETE Endpoint: /api/workspaces/{id}/environments/{environmentID}

​
Path Parameters

​
id
string
required
Workspace ID (UUID)
​
environmentID
string
required
Environment ID to remove (UUID)

​
Response

Status: 200 OK Returns the removed workspace-environment mapping.

​
Get Workspace Designs

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/workspaces/{id}/designs?page=0&pagesize=25"
Method: GET Endpoint: /api/workspaces/{id}/designs

​
Path Parameters

​
id
string
required
Workspace ID (UUID)

​
Query Parameters

​
page
integer
default:"0"
Page number
​
pagesize
integer
default:"20"
Page size
​
search
string
Search term
​
order
string
Order by field
​
filter
string
Filter conditions: {"assigned": true/false, "deleted_at": true/false}
​
visibility
array
Filter by visibility: ["public", "private", "published"]

​
Response

Returns a paginated list of designs (patterns) assigned to this workspace.

​
Add Design to Workspace

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/workspaces/{id}/designs/{designID}
Method: POST Endpoint: /api/workspaces/{id}/designs/{designID}

​
Path Parameters

​
id
string
required
Workspace ID (UUID)
​
designID
string
required
Design ID to add (UUID)

​
Response

Status: 201 Created Returns the workspace-design mapping object.

​
Error Codes

​
400 Bad Request
error
Invalid request parameters or malformed JSON
​
401 Unauthorized
error
Missing or invalid authentication token
​
404 Not Found
error
Workspace not found
​
500 Internal Server Error
error
Server error occurred