PrivateEndpoints - OpenRouter

Overview

Private Endpoints endpoints

Available Operations

list - List private endpoints
create - Create a private endpoint
delete - Delete a private endpoint
get - Get a private endpoint
update - Update a draft private endpoint
activate - Activate a validated private endpoint
disable - Disable a private endpoint
enable - Enable a private endpoint
update_pricing - Set private endpoint pricing
validate - Validate a draft private endpoint

list

List the organization’s private endpoints, including drafts. Requires the private endpoints entitlement. 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.private_endpoints.list()

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`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.ListPrivateEndpointsResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.RequestTimeoutResponseError	408	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

create

Create a private endpoint as a draft. Drafts are not routable: validate one with POST /private-endpoints/{id}/validate, then activate it with POST /private-endpoints/{id}/activate. Pass activate to do all three in one call; if validation fails the draft is kept and returned with the failed checks. Send an Idempotency-Key header to make retries safe: a repeated key with the same request returns the endpoint the first request created; reusing it with different fields returns 422 idempotency_key_reused. 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.private_endpoints.create(model_permaslug="openai/gpt-4o-2024-08-06", provider_slug="azure", upstream_model_id="gpt-4o-prod")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`model_permaslug`	str	✅	Permanent slug of the model this endpoint serves.	openai/gpt-4o-2024-08-06
`provider_slug`	str	✅	Slug of the upstream provider.	azure
`upstream_model_id`	str	✅	Model or deployment identifier sent to the upstream provider.	gpt-4o-prod
`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.
`idempotency_key`	Optional[str]	➖	Retry-safe create: a repeated create with the same key from the same organization returns the endpoint the first request created instead of creating another. The endpoint is returned as it is now. Reusing a key with a different request body (model, provider, base URL, upstream model ID, declared ZDR or region, or pricing) is rejected with 422 `idempotency_key_reused`. `activate` is not compared, and later edits to the endpoint do not affect the comparison.	wayfair-gpt-4o-eastus-2026-09
`activate`	Optional[components.PrivateEndpointActivation]	➖	Validate and activate in the same call. On a failed validation the draft is kept and returned with a 422, so fix it and call `/validate` and `/activate` instead of creating it again.	{ “workspace_id”: “550e8400-e29b-41d4-a716-446655440000” }
`base_url`	Optional[str]	➖	HTTPS base URL of your deployment. Required unless the provider derives its URL from the BYOK credential (Azure, Amazon Bedrock, Google Vertex).	https://contoso.openai.azure.com
`declared_region`	OptionalNullable[components.CreatePrivateEndpointRequestDeclaredRegion]	➖	Attest where this deployment processes data.	us
`declared_zdr`	OptionalNullable[bool]	➖	Attest that this deployment retains no prompt or completion data.
`pricing`	Optional[components.PrivateEndpointPricing]	➖	Negotiated per-token rates reported for requests routed to this endpoint.	{ “cache_read”: “0.00000025”, “cache_write”: “0.000003125”, “completion”: “0.00001”, “prompt”: “0.0000025” }
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.ManagedPrivateEndpointResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.CreatePrivateEndpointValidationFailedResponseError	404	application/json
errors.NotFoundResponseError	404	application/json
errors.RequestTimeoutResponseError	408	application/json
errors.CreatePrivateEndpointValidationFailedResponseError	409	application/json
errors.ConflictResponseError	409	application/json
errors.CreatePrivateEndpointValidationFailedResponseError	422	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.CreatePrivateEndpointValidationFailedResponseError	500	application/json
errors.InternalServerResponseError	500	application/json
errors.CreatePrivateEndpointValidationFailedResponseError	502	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

delete

Delete a private endpoint and stop routing to it. Pass draft_only=true to refuse (409) when the endpoint has been activated. 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.private_endpoints.delete(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`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.
`draft_only`	Optional[operations.DraftOnly]	➖	When `true`, only delete the endpoint if it is still a draft (409 otherwise).
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.DeletePrivateEndpointResponse

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.RequestTimeoutResponseError	408	application/json
errors.ConflictResponseError	409	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get

Get one private endpoint with its upstream configuration and current pricing. 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.private_endpoints.get(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`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.PrivateEndpointResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.RequestTimeoutResponseError	408	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

update

Replace a draft endpoint’s upstream configuration: send upstream_model_id, and base_url to change it (an omitted base_url keeps the stored one). Omitted data-policy declarations are kept while the upstream is unchanged and cleared when it changes. Any change clears earlier validation. Active endpoints return 409; delete and re-create them instead. 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.private_endpoints.update(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11", upstream_model_id="gpt-4o-prod")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`upstream_model_id`	str	✅	Model or deployment identifier sent to the upstream provider.	gpt-4o-prod
`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.
`base_url`	Optional[str]	➖	HTTPS base URL of your deployment. Required unless the provider derives its URL from the BYOK credential (Azure, Amazon Bedrock, Google Vertex).	https://contoso.openai.azure.com
`declared_region`	OptionalNullable[components.UpdatePrivateEndpointRequestDeclaredRegion]	➖	Attest where this deployment processes data.	us
`declared_zdr`	OptionalNullable[bool]	➖	Attest that this deployment retains no prompt or completion data.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.PrivateEndpointResponse

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.RequestTimeoutResponseError	408	application/json
errors.ConflictResponseError	409	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

activate

Make a validated draft routable. Returns 409 when the endpoint was never validated, the validation is stale, or it is already active. 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.private_endpoints.activate(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`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.ManagedPrivateEndpointResponse

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.RequestTimeoutResponseError	408	application/json
errors.ConflictResponseError	409	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

disable

Stop routing to an active endpoint without deleting it. 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.private_endpoints.disable(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`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.ManagedPrivateEndpointResponse

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.RequestTimeoutResponseError	408	application/json
errors.ConflictResponseError	409	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

enable

Resume routing to a disabled endpoint. 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.private_endpoints.enable(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`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.ManagedPrivateEndpointResponse

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.RequestTimeoutResponseError	408	application/json
errors.ConflictResponseError	409	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

update_pricing

Set the negotiated per-token rates reported for requests routed to this endpoint. Applies to drafts and active endpoints; new rates take effect for subsequent requests. The body replaces the whole pricing object: omitting cache_read or cache_write reverts that rate to the provider pricing strategy’s default, even if it was set before. 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.private_endpoints.update_pricing(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11", pricing={
        "completion": "0.00001",
        "prompt": "0.0000025",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`pricing`	components.PrivateEndpointPricing	✅	Negotiated per-token rates reported for requests routed to this endpoint.	{ “cache_read”: “0.00000025”, “cache_write”: “0.000003125”, “completion”: “0.00001”, “prompt”: “0.0000025” }
`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.PrivateEndpointResponse

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.RequestTimeoutResponseError	408	application/json
errors.ConflictResponseError	409	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

validate

Send a live test request to the draft endpoint using the given workspace’s BYOK credential for its provider. A passing validation is required before activation. Failed checks return 200 with passed: false. 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.private_endpoints.validate(id="5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11", workspace_id="550e8400-e29b-41d4-a716-446655440000")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✅	Stable identifier of the private endpoint.	5b1c4c4e-7d0a-4a8e-9f3a-2d6c1b0e8a11
`workspace_id`	str	✅	Workspace whose BYOK credential is used for the live validation call. The workspace must belong to your account.	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.PrivateEndpointValidationResponse

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.RequestTimeoutResponseError	408	application/json
errors.ConflictResponseError	409	application/json
errors.UnprocessableEntityResponseError	422	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	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

​activate

​Example Usage

​Parameters

​Response

​Errors

​disable

​Example Usage

​Parameters

​Response

​Errors

​enable

​Example Usage

​Parameters

​Response

​Errors

​update_pricing

​Example Usage

​Parameters

​Response

​Errors

​validate

​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

activate

Example Usage

Parameters

Response

Errors

disable

Example Usage

Parameters

Response

Errors

enable

Example Usage

Parameters

Response

Errors

update_pricing

Example Usage

Parameters

Response

Errors

validate

Example Usage

Parameters

Response

Errors