Workspaces - OpenRouter | Documentation

Overview

Workspaces endpoints

Available Operations

list - List workspaces
create - Create a workspace
delete - Delete a workspace
get - Get a workspace
update - Update a workspace
list_budgets - List workspace budgets
delete_budget - Delete a workspace budget
set_budget - Create or update a workspace budget
list_members - List workspace members
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

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.list(offset=0, limit=50)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`offset`	OptionalNullable[int]	:heavy_minus_sign:	Number of records to skip for pagination	0
`limit`	Optional[int]	:heavy_minus_sign:	Maximum number of records to return (max 100)	50
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	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

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    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")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`name`	str	:heavy_check_mark:	Name for the new workspace	Production
`slug`	str	:heavy_check_mark:	URL-friendly slug (lowercase alphanumeric segments separated by single hyphens, no leading/trailing hyphens)	production
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`default_image_model`	OptionalNullable[str]	:heavy_minus_sign:	Default image model for this workspace	openai/dall-e-3
`default_provider_sort`	OptionalNullable[str]	:heavy_minus_sign:	Default provider sort preference (price, throughput, latency, exacto)	price
`default_text_model`	OptionalNullable[str]	:heavy_minus_sign:	Default text model for this workspace	openai/gpt-4o
`description`	OptionalNullable[str]	:heavy_minus_sign:	Description of the workspace	Production environment workspace
`io_logging_api_key_ids`	List[int]	:heavy_minus_sign:	Optional array of API key IDs to filter I/O logging	null
`io_logging_sampling_rate`	Optional[float]	:heavy_minus_sign:	Sampling rate for I/O logging (0.0001-1)	1
`is_data_discount_logging_enabled`	Optional[bool]	:heavy_minus_sign:	Whether data discount logging is enabled	true
`is_observability_broadcast_enabled`	Optional[bool]	:heavy_minus_sign:	Whether broadcast is enabled	false
`is_observability_io_logging_enabled`	Optional[bool]	:heavy_minus_sign:	Whether private logging is enabled	false
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	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; remove the keys first. Management key required.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.delete(id="production")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	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

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.get(id="production")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	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

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.update(id="production", name="Updated Workspace", slug="updated-workspace")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`default_image_model`	OptionalNullable[str]	:heavy_minus_sign:	Default image model for this workspace	openai/dall-e-3
`default_provider_sort`	OptionalNullable[str]	:heavy_minus_sign:	Default provider sort preference (price, throughput, latency, exacto)	price
`default_text_model`	OptionalNullable[str]	:heavy_minus_sign:	Default text model for this workspace	openai/gpt-4o
`description`	OptionalNullable[str]	:heavy_minus_sign:	New description for the workspace	Updated description
`io_logging_api_key_ids`	List[int]	:heavy_minus_sign:	Optional array of API key IDs to filter I/O logging	null
`io_logging_sampling_rate`	Optional[float]	:heavy_minus_sign:	Sampling rate for I/O logging (0.0001-1)	1
`is_data_discount_logging_enabled`	Optional[bool]	:heavy_minus_sign:	Whether data discount logging is enabled	true
`is_observability_broadcast_enabled`	Optional[bool]	:heavy_minus_sign:	Whether broadcast is enabled	false
`is_observability_io_logging_enabled`	Optional[bool]	:heavy_minus_sign:	Whether private logging is enabled	false
`name`	Optional[str]	:heavy_minus_sign:	New name for the workspace	Updated Workspace
`slug`	Optional[str]	:heavy_minus_sign:	New URL-friendly slug (lowercase alphanumeric segments separated by single hyphens, no leading/trailing hyphens)	updated-workspace
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	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	/

list_budgets

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

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.list_budgets(id="production")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.ListWorkspaceBudgetsResponse

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	/

delete_budget

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

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.delete_budget(id="production", interval="monthly")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`interval`	components.WorkspaceBudgetInterval	:heavy_check_mark:	Budget reset interval. Use “lifetime” for a one-time budget that never resets.	monthly
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.DeleteWorkspaceBudgetResponse

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	/

set_budget

Create or update the budget for a given interval. Budget limits must strictly decrease as the interval narrows (lifetime > monthly > weekly > daily). The optional include_byok_in_budgets flag is a workspace-wide setting: when provided it applies to every budget interval for the workspace, not just the interval in this request. Note that a change made here is applied to budget enforcement immediately, but an already-open workspace settings page in the web dashboard may keep showing the previous value until it is reloaded. Management key required.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.set_budget(id="production", interval="monthly", limit_usd=100, include_byok_in_budgets=True)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`interval`	components.WorkspaceBudgetInterval	:heavy_check_mark:	Budget reset interval. Use “lifetime” for a one-time budget that never resets.	monthly
`limit_usd`	float	:heavy_check_mark:	Spending limit in USD. Must be greater than 0.	100
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`include_byok_in_budgets`	Optional[bool]	:heavy_minus_sign:	Whether to include BYOK (bring-your-own-key) spend when enforcing the workspace’s budgets. This is a workspace-wide setting: it applies to every budget interval (daily, weekly, monthly, and lifetime), not just the interval being upserted in this request. Omit to leave the current setting unchanged.	true
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.UpsertWorkspaceBudgetResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

list_members

List all members of a workspace. Returns paginated results. For the default workspace, returns all organization members (implicit membership). Management key required.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.list_members(id="production", offset=0, limit=50)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`offset`	OptionalNullable[int]	:heavy_minus_sign:	Number of records to skip for pagination	0
`limit`	Optional[int]	:heavy_minus_sign:	Maximum number of records to return (max 100)	50
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

operations.ListWorkspaceMembersResponse

Errors

Error Type	Status Code	Content Type
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

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.bulk_add_members(id="production", user_ids=[
        "user_abc123",
        "user_def456",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`user_ids`	List[str]	:heavy_check_mark:	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]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	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. SCIM-managed members cannot be removed; changes must be made in your identity provider. Management key required.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.workspaces.bulk_remove_members(id="production", user_ids=[
        "user_abc123",
        "user_def456",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	:heavy_check_mark:	The workspace ID (UUID) or slug	production
`user_ids`	List[str]	:heavy_check_mark:	List of user IDs to remove from the workspace	[ “user_abc123”, “user_def456” ]
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	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	/

​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

​list_budgets

​Example Usage

​Parameters

​Response

​Errors

​delete_budget

​Example Usage

​Parameters

​Response

​Errors

​set_budget

​Example Usage

​Parameters

​Response

​Errors

​list_members

​Example Usage

​Parameters

​Response

​Errors

​bulk_add_members

​Example Usage

​Parameters

​Response

​Errors

​bulk_remove_members

​Example Usage

​Parameters

​Response

​Errors

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

list_budgets

Example Usage

Parameters

Response

Errors

delete_budget

Example Usage

Parameters

Response

Errors

set_budget

Example Usage

Parameters

Response

Errors

list_members

Example Usage

Parameters

Response

Errors

bulk_add_members

Example Usage

Parameters

Response

Errors

bulk_remove_members

Example Usage

Parameters

Response

Errors