Workspaces - Python SDK

Workspaces method reference

Overview

Workspaces endpoints

Available Operations

list

List all workspaces for the authenticated user. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with 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

ParameterTypeRequiredDescriptionExample
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
offsetOptional[int]Number of records to skip for pagination0
limitOptional[int]Maximum number of records to return (max 100)50
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListWorkspacesResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

create

Create a new workspace for the authenticated user. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with 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

ParameterTypeRequiredDescriptionExample
namestr✔️Name for the new workspaceProduction
slugstr✔️URL-friendly slug (lowercase alphanumeric segments separated by single hyphens, no leading/trailing hyphens)production
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
default_image_modelOptionalNullable[str]Default image model for this workspaceopenai/dall-e-3
default_provider_sortOptionalNullable[str]Default provider sort preference (price, throughput, latency, exacto)price
default_text_modelOptionalNullable[str]Default text model for this workspaceopenai/gpt-4o
descriptionOptionalNullable[str]Description of the workspaceProduction environment workspace
io_logging_api_key_idsList[int]Optional array of API key IDs to filter I/O logging<nil>
io_logging_sampling_rateOptional[float]Sampling rate for I/O logging (0.0001-1)1
is_data_discount_logging_enabledOptional[bool]Whether data discount logging is enabledtrue
is_observability_broadcast_enabledOptional[bool]Whether broadcast is enabledfalse
is_observability_io_logging_enabledOptional[bool]Whether private logging is enabledfalse
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.CreateWorkspaceResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 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

1from openrouter import OpenRouter
2import os
3
4with 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

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.DeleteWorkspaceResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

get

Get a single workspace by ID or slug. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with 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

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.GetWorkspaceResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

update

Update an existing workspace by ID or slug. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with 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

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
default_image_modelOptionalNullable[str]Default image model for this workspaceopenai/dall-e-3
default_provider_sortOptionalNullable[str]Default provider sort preference (price, throughput, latency, exacto)price
default_text_modelOptionalNullable[str]Default text model for this workspaceopenai/gpt-4o
descriptionOptionalNullable[str]New description for the workspaceUpdated description
io_logging_api_key_idsList[int]Optional array of API key IDs to filter I/O logging<nil>
io_logging_sampling_rateOptional[float]Sampling rate for I/O logging (0.0001-1)1
is_data_discount_logging_enabledOptional[bool]Whether data discount logging is enabledtrue
is_observability_broadcast_enabledOptional[bool]Whether broadcast is enabledfalse
is_observability_io_logging_enabledOptional[bool]Whether private logging is enabledfalse
nameOptional[str]New name for the workspaceUpdated Workspace
slugOptional[str]New URL-friendly slug (lowercase alphanumeric segments separated by single hyphens, no leading/trailing hyphens)updated-workspace
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.UpdateWorkspaceResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

list_budgets

List all budgets configured for a workspace. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with 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_budgets(id="production")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.ListWorkspaceBudgetsResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

delete_budget

Remove the budget for a given interval. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with 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_budget(id="production", interval="monthly")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
intervalcomponents.WorkspaceBudgetInterval✔️Budget reset interval. Use “lifetime” for a one-time budget that never resets.monthly
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.DeleteWorkspaceBudgetResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

set_budget

Create or update the budget for a given interval. Budget limits must strictly decrease as the interval narrows (lifetime > monthly > weekly > daily). Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with 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.set_budget(id="production", interval="monthly", limit_usd=100)
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
intervalcomponents.WorkspaceBudgetInterval✔️Budget reset interval. Use “lifetime” for a one-time budget that never resets.monthly
limit_usdfloat✔️Spending limit in USD. Must be greater than 0.100
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.UpsertWorkspaceBudgetResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 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

1from openrouter import OpenRouter
2import os
3
4with 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

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
user_idsList[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_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.BulkAddWorkspaceMembersResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 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

1from openrouter import OpenRouter
2import os
3
4with 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

ParameterTypeRequiredDescriptionExample
idstr✔️The workspace ID (UUID) or slugproduction
user_idsList[str]✔️List of user IDs to remove from the workspace[
“user_abc123”,
“user_def456”
]
http_refererOptional[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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.BulkRemoveWorkspaceMembersResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.NotFoundResponseError404application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*