Workspaces - Python SDK
Workspaces - Python SDK
The Python SDK and docs are currently in beta. Report issues on GitHub.
Overview
Workspaces endpoints
Available Operations
- list - List workspaces
- create - Create a workspace
- delete - Delete a workspace
- get - Get a workspace
- update - Update a workspace
- bulk_add_members - Bulk add members to a workspace
- bulk_remove_members - Bulk remove members from a workspace
list
List all workspaces for the authenticated user. Management key required.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.workspaces.list() 12 13 while res is not None: 14 # Handle items 15 16 res = res.next()
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
offset | Optional[int] | ➖ | Number of records to skip for pagination | 0 |
limit | Optional[int] | ➖ | Maximum number of records to return (max 100) | 50 |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
operations.ListWorkspacesResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
create
Create a new workspace for the authenticated user. Management key required.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.workspaces.create(name="Production", slug="production", default_image_model="openai/dall-e-3", default_provider_sort="price", default_text_model="openai/gpt-4o", description="Production environment workspace") 12 13 # Handle response 14 print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
name | str | ✔️ | Name for the new workspace | Production |
slug | str | ✔️ | URL-friendly slug (lowercase alphanumeric and hyphens only) | production |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
default_image_model | OptionalNullable[str] | ➖ | Default image model for this workspace | openai/dall-e-3 |
default_provider_sort | OptionalNullable[str] | ➖ | Default provider sort preference (price, throughput, latency, exacto) | price |
default_text_model | OptionalNullable[str] | ➖ | Default text model for this workspace | openai/gpt-4o |
description | OptionalNullable[str] | ➖ | Description of the workspace | Production environment workspace |
is_data_discount_logging_enabled | Optional[bool] | ➖ | Whether data discount logging is enabled | true |
is_observability_broadcast_enabled | Optional[bool] | ➖ | Whether broadcast is enabled | false |
is_observability_io_logging_enabled | Optional[bool] | ➖ | Whether private logging is enabled | false |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.CreateWorkspaceResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
delete
Delete an existing workspace. The default workspace cannot be deleted. Workspaces with active API keys cannot be deleted. Management key required.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.workspaces.delete(id="production") 12 13 # Handle response 14 print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | ✔️ | The workspace ID (UUID) or slug | production |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.DeleteWorkspaceResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
get
Get a single workspace by ID or slug. Management key required.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.workspaces.get(id="production") 12 13 # Handle response 14 print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | ✔️ | The workspace ID (UUID) or slug | production |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.GetWorkspaceResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
update
Update an existing workspace by ID or slug. Management key required.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.workspaces.update(id="production", name="Updated Workspace", slug="updated-workspace") 12 13 # Handle response 14 print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | ✔️ | The workspace ID (UUID) or slug | production |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
default_image_model | OptionalNullable[str] | ➖ | Default image model for this workspace | openai/dall-e-3 |
default_provider_sort | OptionalNullable[str] | ➖ | Default provider sort preference (price, throughput, latency, exacto) | price |
default_text_model | OptionalNullable[str] | ➖ | Default text model for this workspace | openai/gpt-4o |
description | OptionalNullable[str] | ➖ | New description for the workspace | Updated description |
is_data_discount_logging_enabled | Optional[bool] | ➖ | Whether data discount logging is enabled | true |
is_observability_broadcast_enabled | Optional[bool] | ➖ | Whether broadcast is enabled | false |
is_observability_io_logging_enabled | Optional[bool] | ➖ | Whether private logging is enabled | false |
name | Optional[str] | ➖ | New name for the workspace | Updated Workspace |
slug | Optional[str] | ➖ | New URL-friendly slug | updated-workspace |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.UpdateWorkspaceResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
bulk_add_members
Add multiple organization members to a workspace. Members are assigned the same role they hold in the organization. Management key required.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.workspaces.bulk_add_members(id="production", user_ids=[ 12 "user_abc123", 13 "user_def456", 14 ]) 15 16 # Handle response 17 print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | ✔️ | The workspace ID (UUID) or slug | production |
user_ids | List[str] | ✔️ | List of user IDs to add to the workspace. Members are assigned the same role they hold in the organization. | [ “user_abc123”, “user_def456” ] |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.BulkAddWorkspaceMembersResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
bulk_remove_members
Remove multiple members from a workspace. Members with active API keys in the workspace cannot be removed. Management key required.
Example Usage
1 from openrouter import OpenRouter 2 import os 3 4 with OpenRouter( 5 http_referer="<value>", 6 x_open_router_title="<value>", 7 x_open_router_categories="<value>", 8 api_key=os.getenv("OPENROUTER_API_KEY", ""), 9 ) as open_router: 10 11 res = open_router.workspaces.bulk_remove_members(id="production", user_ids=[ 12 "user_abc123", 13 "user_def456", 14 ]) 15 16 # Handle response 17 print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | ✔️ | The workspace ID (UUID) or slug | production |
user_ids | List[str] | ✔️ | List of user IDs to remove from the workspace | [ “user_abc123”, “user_def456” ] |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.BulkRemoveWorkspaceMembersResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |