airbyte/docs/ai-agents/embedded/api/workspaces.md

Workspace Management

Workspaces in Airbyte represent logical containers for your data integration pipelines. Each workspace can contain multiple sources, destinations, and connections. The Workspace Management API allows you to programmatically list, retrieve, update, and manage workspaces within your organization.

Overview

The Workspace API provides comprehensive management capabilities:

• List workspaces with filtering and pagination
• Get workspace details by ID
• Update workspace name and status
• Delete workspaces (soft delete)
• View workspace statistics (active/inactive counts)
• Sync workspaces from Airbyte Cloud to your local database

All workspace endpoints require Operator Bearer Token authentication.

Workspace status

Each workspace has a status that controls its availability:

• active - Workspace is active and all connections can run normally
• inactive - Workspace is inactive; setting this status automatically disables all active connections

List workspaces

Retrieve a paginated list of workspaces for your organization.

Endpoint

GET https://api.airbyte.ai/api/v1/workspaces

Query parameters

Parameter	Type	Required	Default	Description
name_contains	string	No	-	Filter workspaces by name (case-insensitive partial match)
status	string	No	-	Filter by status: active or inactive. Returns all if not specified
limit	integer	No	20	Maximum number of workspaces to return (max: 100)
cursor	string	No	-	Opaque pagination cursor from previous response

Request example

curl https://api.airbyte.ai/api/v1/workspaces?limit=50&status=active \

  -H 'Authorization: Bearer <your_operator_token>'

Response example

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
      "name": "Production Workspace",
      "organization_id": "12345678-1234-1234-1234-123456789012",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-f6g7-8901-bc23-de45fg678901",
      "name": "Development Workspace",
      "organization_id": "12345678-1234-1234-1234-123456789012",
      "status": "active",
      "created_at": "2025-01-10T14:20:00Z",
      "updated_at": "2025-01-12T09:15:00Z"
    }
  ],
  "next": "https://api.airbyte.ai/api/v1/workspaces?limit=50&cursor=eyJvZmZzZXQiOjUwfQ=="
}

Response fields

Field	Type	Description
data	array	List of workspace objects
next	string	URL for the next page of results (null if no more pages)

Workspace object

Field	Type	Description
id	UUID	Unique identifier for the workspace
name	string	Workspace name
organization_id	UUID	Organization that owns this workspace
status	string	Workspace status: active or inactive
created_at	datetime	Timestamp when the workspace was created
updated_at	datetime	Timestamp when the workspace was last updated

Pagination

The API uses cursor-based pagination. To retrieve the next page:

1. Check the next field in the response
2. If next is not null, make a GET request to that URL
3. Continue until next is null

Example pagination workflow:

# First page
curl https://api.airbyte.ai/api/v1/workspaces?limit=20 \

  -H 'Authorization: Bearer <your_token>'

# Use the 'next' URL from the response for the second page
curl https://api.airbyte.ai/api/v1/workspaces?limit=20&cursor=eyJvZmZzZXQiOjIwfQ== \

  -H 'Authorization: Bearer <your_token>'

Filtering examples

Filter by name:

curl https://api.airbyte.ai/api/v1/workspaces?name_contains=prod \

  -H 'Authorization: Bearer <your_token>'

Filter by status:

curl https://api.airbyte.ai/api/v1/workspaces?status=active \

  -H 'Authorization: Bearer <your_token>'

Combined filters:

curl https://api.airbyte.ai/api/v1/workspaces?status=active&name_contains=dev&limit=10 \

  -H 'Authorization: Bearer <your_token>'

Get workspace

Retrieve details for a specific workspace.

Endpoint

GET https://api.airbyte.ai/api/v1/workspaces/{workspace ID}

Path parameters

Parameter	Type	Required	Description
workspace ID	UUID	Yes	Unique identifier of the workspace

Request example

curl https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \

  -H 'Authorization: Bearer <your_operator_token>'

Response example

{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "name": "Production Workspace",
  "organization_id": "12345678-1234-1234-1234-123456789012",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Update workspace

Update a workspace's name and/or status.

Endpoint

PUT https://api.airbyte.ai/api/v1/workspaces/{workspace ID}

Path parameters

Parameter	Type	Required	Description
workspace ID	UUID	Yes	Unique identifier of the workspace

Request body

Field	Type	Required	Description
name	string	No	New name for the workspace
status	string	No	New status: active or inactive

Important behavior

When setting status to inactive, all active connections in the workspace will be automatically disabled. This ensures that no data syncs occur while the workspace is inactive.

Request example

Update workspace name:

curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \

  -H 'Authorization: Bearer <your_operator_token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "name": "Production Workspace - Updated"
  }'

Change workspace status to inactive:

curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \

  -H 'Authorization: Bearer <your_operator_token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "status": "inactive"
  }'

Update both name and status:

curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \

  -H 'Authorization: Bearer <your_operator_token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "name": "Archived Production",
    "status": "inactive"
  }'

Response example

{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "name": "Production Workspace - Updated",
  "organization_id": "12345678-1234-1234-1234-123456789012",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-10-08T15:45:00Z"
}

Delete workspace

Delete a workspace from both Airbyte Cloud and mark it as deleted locally (soft delete).

Endpoint

DELETE https://api.airbyte.ai/api/v1/workspaces/{workspace ID}

Path parameters

Parameter	Type	Required	Description
workspace ID	UUID	Yes	Unique identifier of the workspace

Request example

curl -X DELETE https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \

  -H 'Authorization: Bearer <your_operator_token>'

Response example

{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "deleted_at": "2025-10-08T16:00:00Z"
}

Important notes

• This performs a soft delete in the local database
• The workspace is deleted from Airbyte Cloud
• All associated resources (sources, destinations, connections) will also be deleted

Get workspace statistics

Retrieve statistics about workspaces in your organization.

Endpoint

GET https://api.airbyte.ai/api/v1/workspaces/stats

Request example

curl https://api.airbyte.ai/api/v1/workspaces/stats \

  -H 'Authorization: Bearer <your_operator_token>'

Response example

{
  "active_count": 12,
  "inactive_count": 3,
  "total_count": 15
}

Response fields

Field	Type	Description
active_count	integer	Number of workspaces with status active
inactive_count	integer	Number of workspaces with status inactive
total_count	integer	Total number of workspaces

Response fields

Field	Type	Description
total_count	integer	Total number of workspaces found in Airbyte Cloud
created_count	integer	Number of new workspaces created locally
created_workspace IDs	array of UUIDs	IDs of the newly created workspaces

Common use cases

Monitor workspace health

Combine workspace stats and listing to monitor your organization:

# Get overview statistics
curl https://api.airbyte.ai/api/v1/workspaces/stats \

  -H 'Authorization: Bearer <your_token>'

# List inactive workspaces for review
curl https://api.airbyte.ai/api/v1/workspaces?status=inactive \

  -H 'Authorization: Bearer <your_token>'

Deactivate workspace and connections

When you need to pause all activity in a workspace:

curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \

  -H 'Authorization: Bearer <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "status": "inactive"
  }'

This automatically disables all connections, preventing any data syncs.

Search for workspaces

Find workspaces by name pattern:

# Find all production workspaces
curl https://api.airbyte.ai/api/v1/workspaces?name_contains=production \

  -H 'Authorization: Bearer <your_token>'

Error responses

401 unauthorized

{
  "detail": "Invalid authentication credentials"
}

Cause: Missing or invalid Operator Bearer Token

Solution: Ensure you're using a valid operator token in the Authorization header

404 not found

{
  "detail": "Workspace not found"
}

Cause: The specified workspace ID does not exist

Solution: Verify the workspace ID and ensure it belongs to your organization

422 validation error

{
  "detail": [
    {
      "loc": ["body", "status"],
      "msg": "value is not a valid enumeration member; permitted: 'active', 'inactive'",
      "type": "type_error.enum"
    }
  ]
}

Cause: Invalid request parameters

Solution: Check that all parameters match the expected format and values