For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
ModelsChatRankingsDocs
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
    • Overview
    • Usage for Agents
  • TypeScript SDK
    • Overview
  • Python SDK
    • Overview
      • Analytics
      • APIKeys
      • Byok
      • Chat
      • Credits
      • Embeddings
      • Endpoints
      • Generations
      • Guardrails
      • OAuth
      • Observability
      • Organization
      • Presets
      • Providers
      • Rerank
      • Beta.Responses
      • Transcriptions
      • Speech
      • VideoGeneration
      • Workspaces
  • Go SDK
  • DevTools
    • Overview
    • Migrating to @openrouter/agent
LogoLogo
ModelsChatRankingsDocs
On this page
  • Overview
  • Available Operations
  • list
  • Example Usage
  • Parameters
  • Response
  • Errors
  • create
  • Example Usage
  • Parameters
  • Response
  • Errors
  • delete
  • Example Usage
  • Parameters
  • Response
  • Errors
  • get
  • Example Usage
  • Parameters
  • Response
  • Errors
  • update
  • Example Usage
  • Parameters
  • Response
  • Errors
  • bulk_add_members
  • Example Usage
  • Parameters
  • Response
  • Errors
  • bulk_remove_members
  • Example Usage
  • Parameters
  • Response
  • Errors
Python SDKAPI Reference

Workspaces - Python SDK

Workspaces method reference
Was this page helpful?
Previous

Analytics - Go SDK

Analytics method reference
Next
Built with

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

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*/*

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*/*