openrouter-python-sdk-retry-errors/docs/sdks/guardrails

Guardrails

Overview

Guardrails endpoints

Available Operations

• list - List guardrails
• create - Create a guardrail
• delete - Delete a guardrail
• get - Get a guardrail
• update - Update a guardrail
• list_guardrail_key_assignments - List key assignments for a guardrail
• bulk_assign_keys - Bulk assign keys to a guardrail
• bulk_unassign_keys - Bulk unassign keys from a guardrail
• list_guardrail_member_assignments - List member assignments for a guardrail
• bulk_assign_members - Bulk assign members to a guardrail
• bulk_unassign_members - Bulk unassign members from a guardrail
• list_key_assignments - List all key assignments
• list_member_assignments - List all member assignments

list

List all guardrails 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.guardrails.list()

    while res is not None:
        # Handle items

        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.ListGuardrailsResponse

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 guardrail 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.guardrails.create(name="My New Guardrail", allowed_models=None, allowed_providers=[
        "openai",
        "anthropic",
        "deepseek",
    ], description="A guardrail for limiting API usage", enforce_zdr=False, ignored_models=None, ignored_providers=None, limit_usd=50, reset_interval="monthly")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
name	str	✔️	Name for the new guardrail	My New Guardrail
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.
allowed_models	List[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" ]
allowed_providers	List[str]	➖	List of allowed provider IDs	[ "openai", "anthropic", "deepseek" ]
description	OptionalNullable[str]	➖	Description of the guardrail	A guardrail for limiting API usage
enforce_zdr	OptionalNullable[bool]	➖	Whether to enforce zero data retention	false
ignored_models	List[str]	➖	Array of model identifiers to exclude from routing (slug or canonical_slug accepted)	[ "openai/gpt-4o-mini" ]
ignored_providers	List[str]	➖	List of provider IDs to exclude from routing	[ "azure" ]
limit_usd	OptionalNullable[float]	➖	Spending limit in USD	50
reset_interval	OptionalNullable[components.GuardrailInterval]	➖	Interval at which the limit resets (daily, weekly, monthly)	monthly
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.CreateGuardrailResponse

Errors

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

delete

Delete an existing guardrail. 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.guardrails.delete(id="550e8400-e29b-41d4-a716-446655440000")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail to delete	550e8400-e29b-41d4-a716-446655440000
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.DeleteGuardrailResponse

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

get

Get a single guardrail by ID. 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.guardrails.get(id="550e8400-e29b-41d4-a716-446655440000")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail to retrieve	550e8400-e29b-41d4-a716-446655440000
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.GetGuardrailResponse

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 guardrail. 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.guardrails.update(id="550e8400-e29b-41d4-a716-446655440000", description="Updated description", limit_usd=75, name="Updated Guardrail Name", reset_interval="weekly")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail to update	550e8400-e29b-41d4-a716-446655440000
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.
allowed_models	List[str]	➖	Array of model identifiers (slug or canonical_slug accepted)	[ "openai/gpt-5.2" ]
allowed_providers	List[str]	➖	New list of allowed provider IDs	[ "openai", "anthropic", "deepseek" ]
description	OptionalNullable[str]	➖	New description for the guardrail	Updated description
enforce_zdr	OptionalNullable[bool]	➖	Whether to enforce zero data retention	true
ignored_models	List[str]	➖	Array of model identifiers to exclude from routing (slug or canonical_slug accepted)	[ "openai/gpt-4o-mini" ]
ignored_providers	List[str]	➖	List of provider IDs to exclude from routing	[ "azure" ]
limit_usd	OptionalNullable[float]	➖	New spending limit in USD	75
name	Optional[str]	➖	New name for the guardrail	Updated Guardrail Name
reset_interval	OptionalNullable[components.GuardrailInterval]	➖	Interval at which the limit resets (daily, weekly, monthly)	monthly
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.UpdateGuardrailResponse

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_guardrail_key_assignments

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

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail	550e8400-e29b-41d4-a716-446655440000
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.ListGuardrailKeyAssignmentsResponse

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

bulk_assign_keys

Assign multiple API keys to a specific guardrail. 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.guardrails.bulk_assign_keys(id="550e8400-e29b-41d4-a716-446655440000", key_hashes=[
        "c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail	550e8400-e29b-41d4-a716-446655440000
key_hashes	List[str]	✔️	Array of API key hashes to assign to the guardrail	[ "c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93" ]
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.BulkAssignKeysResponse

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

bulk_unassign_keys

Unassign multiple API keys from a specific guardrail. 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.guardrails.bulk_unassign_keys(id="550e8400-e29b-41d4-a716-446655440000", key_hashes=[
        "c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail	550e8400-e29b-41d4-a716-446655440000
key_hashes	List[str]	✔️	Array of API key hashes to unassign from the guardrail	[ "c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93" ]
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.BulkUnassignKeysResponse

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_guardrail_member_assignments

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

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail	550e8400-e29b-41d4-a716-446655440000
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.ListGuardrailMemberAssignmentsResponse

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

bulk_assign_members

Assign multiple organization members to a specific guardrail. 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.guardrails.bulk_assign_members(id="550e8400-e29b-41d4-a716-446655440000", member_user_ids=[
        "user_abc123",
        "user_def456",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail	550e8400-e29b-41d4-a716-446655440000
member_user_ids	List[str]	✔️	Array of member user IDs to assign to the guardrail	[ "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.BulkAssignMembersResponse

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

bulk_unassign_members

Unassign multiple organization members from a specific guardrail. 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.guardrails.bulk_unassign_members(id="550e8400-e29b-41d4-a716-446655440000", member_user_ids=[
        "user_abc123",
        "user_def456",
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
id	str	✔️	The unique identifier of the guardrail	550e8400-e29b-41d4-a716-446655440000
member_user_ids	List[str]	✔️	Array of member user IDs to unassign from the guardrail	[ "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.BulkUnassignMembersResponse

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_key_assignments

List all API key guardrail assignments 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.guardrails.list_key_assignments()

    while res is not None:
        # Handle items

        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.ListKeyAssignmentsResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	*/*

list_member_assignments

List all organization member guardrail assignments 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.guardrails.list_member_assignments()

    while res is not None:
        # Handle items

        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.ListMemberAssignmentsResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	*/*