Gateway to Other APIs

Forward requests to provider paths outside unified routes (rerank, video, listen, and more) through https://api.portkey.ai/v1/… Same auth, configs, retries, logging, and analytics as first-class gateway traffic.

Available on all Portkey plans.

Prefer unified routes for chat, images, embeddings, messages, responses, and audio—they stay consistent across 250+ models.

Create an API key from API Keys when onboarding.

Quick start

curl https://api.portkey.ai/v1/<provider-path> \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{ ... }'

Replace <provider-path> with the suffix the provider expects (rerank, videos, listen, etc.). On a self-hosted gateway, use that deployment’s host; keep the /v1/<provider-path> pattern.

Unified routes vs proxy

Dedicated routes register before the catch-all. They use unified handlers—not the proxy.

Path	Handler
POST /v1/chat/completions	Chat completions
POST /v1/images/generations	Unified image handler
POST /v1/embeddings	Unified embeddings handler
POST /v1/messages	Messages API
POST /v1/responses	Responses API
POST /v1/audio/...	Unified audio handler
/v1/files, /v1/batches, …	Dedicated handlers
Anything else under /v1/*	Proxy handler

Pick a URL

Goal	URL
Chat (configs, fallbacks, retries)	POST https://api.portkey.ai/v1/chat/completions (unified)
Image generation	POST https://api.portkey.ai/v1/images/generations (unified)
Provider path without a unified route	POST https://api.portkey.ai/v1/<that-path> (proxy)
Force proxy on a path that would hit a unified route	POST https://api.portkey.ai/v1/proxy/<that-path> — see Legacy /v1/proxy

POST https://api.portkey.ai/v1/chat/completions does not use the proxy. A dedicated chat handler runs first.

How the proxy works

For paths that reach the proxy:

1. Send method, path, query string, and body (JSON, multipart, or binary) to the gateway.
2. Portkey applies auth, config, credentials, routing, retries, caching, guardrails, and the rest of the gateway pipeline.
3. The request is sent to the provider base URL (or x-portkey-custom-host) with the remaining path the provider expects.
4. The response is essentially the provider response (pass-through), plus standard Portkey response headers.

Fallback, load balancing, and conditional routing use the same config engine as every other gateway call.

Supported HTTP methods

Method	Supported
POST	Yes
GET	Yes (realtime path excluded on Workers)
PUT	Yes
DELETE	Yes
PATCH	No — not registered on the /v1/* catch-all

Required and optional headers

Required

Header	Purpose
x-portkey-api-key	Portkey API key
x-portkey-provider or x-portkey-config	Routing: provider slug, Model Catalog @slug, or full config JSON
Authorization	Provider secret when credentials are not supplied only via Model Catalog
Content-Type	Match the provider (application/json for JSON bodies)

Optional

Header	Purpose
x-portkey-metadata	JSON tags for analytics and conditional routing
x-portkey-custom-host	Override provider base URL — Custom hosts
x-portkey-forward-headers	Comma-separated client header names to forward upstream

x-portkey-* headers are consumed by the gateway and not forwarded as arbitrary upstream passthrough. Store secrets in Authorization (or the header the provider expects), or in Model Catalog.

Full header list: Inference API headers.

Authenticate

Model Catalog (recommended)

Add credentials in Model Catalog. Use x-portkey-provider: @<slug> and omit Authorization when the catalog supplies auth.

cURL

curl https://api.portkey.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @cohere-prod"

Model Catalog centralizes keys, budget and rate limits, and rotation.

Direct provider auth

Use a supported provider slug and pass the provider secret on each request.

cURL

curl https://api.portkey.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: cohere" \
  -H "Authorization: Bearer $COHERE_API_KEY"

Custom hosted endpoint

Choose a compatible x-portkey-provider (openai, cohere, etc.). Set the URL with x-portkey-custom-host (header) or custom_host / customHost in the SDK.

cURL

curl https://api.portkey.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: cohere" \
  -H "x-portkey-custom-host: https://your-public-host.example.com/v1" \
  -H "Authorization: Bearer $COHERE_API_KEY"

On Portkey SaaS, custom hosts must be publicly reachable. Private IPs apply only to self-hosted / hybrid enterprise setups. See Custom hosts.

Base URL for all proxy paths: https://api.portkey.ai/v1 plus the provider suffix (e.g. https://api.portkey.ai/v1/rerank).

Examples

POST /rerank (Model Catalog)

cURL

curl https://api.portkey.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @cohere-prod" \
  -d '{
    "model": "rerank-english-v2.0",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a branch of AI focused on building systems that learn from data.",
      "Data science involves analyzing and interpreting complex data sets."
    ]
  }'

POST /videos (direct provider auth)

Replace the body with the payload the provider’s video API expects.

cURL

curl https://api.portkey.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "sora-1",
    "prompt": "A red balloon floating over a city skyline at sunset"
  }'

GET, PUT, DELETE

The SDK exposes .get(), .post(), .put(), and .delete() for proxy paths.

cURL

curl https://api.portkey.ai/v1/collections \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @provider-prod"

curl -X PUT https://api.portkey.ai/v1/collections/my-collection \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @provider-prod" \
  -d '{"metadata": {"description": "Updated description"}}'

curl -X DELETE https://api.portkey.ai/v1/collections/my-collection \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @provider-prod"

Custom host (full POST /rerank)

cURL

curl https://api.portkey.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: cohere" \
  -H "x-portkey-custom-host: https://your-public-host.example.com/v1" \
  -H "Authorization: Bearer $COHERE_API_KEY" \
  -d '{"model":"rerank-english-v2.0","query":"What is machine learning?","documents":["Document one.","Document two."]}'

Fallback with x-portkey-config

Same JSON shape as Configs: strategies, targets, retries, hooks.

curl https://api.portkey.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-config: {\"strategy\":{\"mode\":\"fallback\"},\"targets\":[{\"provider\":\"@cohere-prod\"},{\"provider\":\"@cohere-backup\"}]}" \
  -d '{"model":"rerank-english-v2.0","query":"...","documents":["..."]}'

Minify JSON for the header (e.g. jq -c . config.json) or set the header in application code.

Root-level options in x-portkey-config is rejected. Use the current config shape (strategy, targets, per-target fields).

Legacy /v1/proxy prefix

Prefix with /v1/proxy so the gateway strips that segment and forwards the remainder—forcing proxy semantics on a path that would otherwise hit a unified handler (raw passthrough on chat/completions, for example).

curl https://api.portkey.ai/v1/proxy/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"Hello"}]}'

For new work, prefer a unified route or a distinct proxy path. Use /v1/proxy/... only when passthrough on a unified path is required.

Advanced examples

Cohere rerank (extended parameters)

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="@COHERE_VIRTUAL_KEY",
)

response = portkey.post(
    "/rerank",
    return_documents=False,
    max_chunks_per_doc=10,
    model="rerank-english-v2.0",
    query="What is the capital of the United States?",
    documents=[
        "Carson City is the capital city of the American state of Nevada.",
        "Washington, D.C. is the capital of the United States.",
        "Capital punishment has existed in the United States since before its founding.",
    ],
)

AWS Bedrock rerank

For Bedrock, pass the full ARN with the model name in the model field.

cURL

curl https://api.portkey.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @BEDROCK_PROVIDER_SLUG" \
  -d '{
    "model": "arn:aws:bedrock:us-east-1::foundation-model/cohere.rerank-v3-5:0",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
      "Carson City is the capital city of the American state of Nevada.",
      "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
      "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
      "Capitalization or capitalisation in English grammar is the use of a capital letter at the start of a word. English usage varies from capitalization in other languages.",
      "Capital punishment has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
    ]
  }'

Tokens, pricing, and analytics

• Token / usage fields in the body come from the provider, same as calling them without Portkey.
• Portkey billing and analytics run on proxy traffic. Pricing accuracy depends on endpoint and model recognition; unusual paths may need cost / pricing configuration—validate in the dashboard or contact support if numbers look off.
• Proxy requests appear in logs like any other gateway call.

Limitations and gotchas

• Response bodies are pass-through from the provider—no Portkey JSON reshape on proxy routes.
• PATCH is not supported on the proxy catch-all.
• Streaming, multipart, and binary use different internal paths—validate with the exact content type and provider before production.
• End-to-end success still requires gateway support for that provider (auth, signing, allowed paths) and a real provider API behind the path.
• SDKs typed for one provider’s contract can break when the upstream changes—same as calling that provider directly.

Checklist

• Prefer a unified route when one exists.
• Send x-portkey-api-key.
• Send x-portkey-provider or x-portkey-config.
• Keep provider secrets in Authorization or Model Catalog—not in x-portkey-* headers as fake “secrets.”
• Match the provider’s request body.
• For passthrough on a unified path, use /v1/proxy/....

Related

• Universal API
• Configs
• Custom hosts
• Inference API headers

Support

Join the Developer Forum for help and discussions.