Guardrails - Python SDK

Guardrails method reference

The Python SDK and docs are currently in beta. Report issues on GitHub.

Overview

Guardrails endpoints

Available Operations

list

List all guardrails 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.guardrails.list()
12
13 # Handle response
14 print(res)

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[str]Number of records to skip for pagination0
limitOptional[str]Maximum number of records to return (max 100)50
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListGuardrailsResponse

Errors

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

create

Create a new guardrail 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.guardrails.create(name="My New Guardrail")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
namestr✔️Name for the new guardrailMy New Guardrail
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.
descriptionOptionalNullable[str]Description of the guardrailA guardrail for limiting API usage
limit_usdOptional[float]Spending limit in USD50
reset_intervalOptionalNullable[operations.CreateGuardrailResetIntervalRequest]Interval at which the limit resets (daily, weekly, monthly)monthly
allowed_providersList[str]List of allowed provider IDs[
“openai”,
“anthropic”,
“deepseek”
]
ignored_providersList[str]List of provider IDs to exclude from routing[
“azure”
]
allowed_modelsList[str]Array of model identifiers (slug or canonical_slug accepted)[
“openai/gpt-5.2”,
“anthropic/claude-4.5-opus-20251124”,
“deepseek/deepseek-r1-0528:free”
]
enforce_zdrOptionalNullable[bool]Whether to enforce zero data retentionfalse
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.CreateGuardrailResponse

Errors

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

get

Get a single guardrail by ID. 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.guardrails.get(id="550e8400-e29b-41d4-a716-446655440000")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail to retrieve550e8400-e29b-41d4-a716-446655440000
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

operations.GetGuardrailResponse

Errors

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

update

Update an existing guardrail. 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.guardrails.update(id="550e8400-e29b-41d4-a716-446655440000")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail to update550e8400-e29b-41d4-a716-446655440000
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.
nameOptional[str]New name for the guardrailUpdated Guardrail Name
descriptionOptionalNullable[str]New description for the guardrailUpdated description
limit_usdOptional[float]New spending limit in USD75
reset_intervalOptionalNullable[operations.UpdateGuardrailResetIntervalRequest]Interval at which the limit resets (daily, weekly, monthly)monthly
allowed_providersList[str]New list of allowed provider IDs[
“openai”,
“anthropic”,
“deepseek”
]
ignored_providersList[str]List of provider IDs to exclude from routing[
“azure”
]
allowed_modelsList[str]Array of model identifiers (slug or canonical_slug accepted)[
“openai/gpt-5.2”
]
enforce_zdrOptionalNullable[bool]Whether to enforce zero data retentiontrue
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.UpdateGuardrailResponse

Errors

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

delete

Delete an existing guardrail. 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.guardrails.delete(id="550e8400-e29b-41d4-a716-446655440000")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail to delete550e8400-e29b-41d4-a716-446655440000
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

operations.DeleteGuardrailResponse

Errors

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

list_key_assignments

List all API key guardrail assignments 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.guardrails.list_key_assignments()
12
13 # Handle response
14 print(res)

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[str]Number of records to skip for pagination0
limitOptional[str]Maximum number of records to return (max 100)50
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListKeyAssignmentsResponse

Errors

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

list_member_assignments

List all organization member guardrail assignments 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.guardrails.list_member_assignments()
12
13 # Handle response
14 print(res)

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[str]Number of records to skip for pagination0
limitOptional[str]Maximum number of records to return (max 100)50
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListMemberAssignmentsResponse

Errors

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

list_guardrail_key_assignments

List all API key assignments for a specific guardrail. 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.guardrails.list_guardrail_key_assignments(id="550e8400-e29b-41d4-a716-446655440000")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail550e8400-e29b-41d4-a716-446655440000
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[str]Number of records to skip for pagination0
limitOptional[str]Maximum number of records to return (max 100)50
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListGuardrailKeyAssignmentsResponse

Errors

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

bulk_assign_keys

Assign multiple API keys to a specific guardrail. 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.guardrails.bulk_assign_keys(id="550e8400-e29b-41d4-a716-446655440000", key_hashes=[
12 "c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93",
13 ])
14
15 # Handle response
16 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail550e8400-e29b-41d4-a716-446655440000
key_hashesList[str]✔️Array of API key hashes to assign to the guardrail[
“c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93”
]
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

operations.BulkAssignKeysToGuardrailResponse

Errors

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

list_guardrail_member_assignments

List all organization member assignments for a specific guardrail. 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.guardrails.list_guardrail_member_assignments(id="550e8400-e29b-41d4-a716-446655440000")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail550e8400-e29b-41d4-a716-446655440000
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[str]Number of records to skip for pagination0
limitOptional[str]Maximum number of records to return (max 100)50
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListGuardrailMemberAssignmentsResponse

Errors

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

bulk_assign_members

Assign multiple organization members to a specific guardrail. 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.guardrails.bulk_assign_members(id="550e8400-e29b-41d4-a716-446655440000", member_user_ids=[
12 "user_abc123",
13 "user_def456",
14 ])
15
16 # Handle response
17 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail550e8400-e29b-41d4-a716-446655440000
member_user_idsList[str]✔️Array of member user IDs to assign to the guardrail[
“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

operations.BulkAssignMembersToGuardrailResponse

Errors

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

bulk_unassign_keys

Unassign multiple API keys from a specific guardrail. 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.guardrails.bulk_unassign_keys(id="550e8400-e29b-41d4-a716-446655440000", key_hashes=[
12 "c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93",
13 ])
14
15 # Handle response
16 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail550e8400-e29b-41d4-a716-446655440000
key_hashesList[str]✔️Array of API key hashes to unassign from the guardrail[
“c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93”
]
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

operations.BulkUnassignKeysFromGuardrailResponse

Errors

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

bulk_unassign_members

Unassign multiple organization members from a specific guardrail. 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.guardrails.bulk_unassign_members(id="550e8400-e29b-41d4-a716-446655440000", member_user_ids=[
12 "user_abc123",
13 "user_def456",
14 ])
15
16 # Handle response
17 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
idstr✔️The unique identifier of the guardrail550e8400-e29b-41d4-a716-446655440000
member_user_idsList[str]✔️Array of member user IDs to unassign from the guardrail[
“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

operations.BulkUnassignMembersFromGuardrailResponse

Errors

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