Base URLs

Every Orq.ai client targets the managed cloud at https://my.orq.ai unless told otherwise. Self-hosted and on-premise deployments serve the same API paths under their own hostname, so every client must be pointed at that hostname explicitly. No client reads the base URL from the environment on its own.

Client	Setting	Managed cloud
Python SDK (`orq-ai-sdk`)	`server_url`	`https://my.orq.ai`
Node.js SDK (`@orq-ai/node`)	`serverURL`	`https://my.orq.ai`
OpenAI-compatible clients	`base_url` / `baseURL`	`https://my.orq.ai/v3/router`
OpenTelemetry exporter	`OTEL_EXPORTER_OTLP_ENDPOINT`	`https://my.orq.ai/v2/otel`

Only the host changes between deployments. The paths stay the same: a deployment reachable at https://orq.example.com serves the router at https://orq.example.com/v3/router and the OTLP endpoint at https://orq.example.com/v2/otel. Set ORQ_BASE_URL alongside ORQ_API_KEY and read both from the environment, so the same code runs against the managed cloud and a self-hosted deployment without edits:

export ORQ_BASE_URL="https://orq.example.com"
export ORQ_API_KEY="<api-key>"

Orq SDKs

Pass the base URL as serverURL (Node.js) or server_url (Python):

import { Orq } from "@orq-ai/node";

const client = new Orq({
  apiKey: process.env.ORQ_API_KEY,
  serverURL: process.env.ORQ_BASE_URL ?? "https://my.orq.ai",
});

import os

from orq_ai_sdk import Orq

client = Orq(
    api_key=os.environ["ORQ_API_KEY"],
    server_url=os.environ.get("ORQ_BASE_URL", "https://my.orq.ai"),
)

The Node.js option is serverURL, with URL in uppercase. serverUrl is not a valid option and leaves the client pointed at the managed cloud.

AI Gateway

OpenAI-compatible clients take the router path as their base URL:

curl -X POST "$ORQ_BASE_URL/v3/router/chat/completions" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: `${process.env.ORQ_BASE_URL ?? "https://my.orq.ai"}/v3/router`,
});

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ORQ_API_KEY"],
    base_url=f"{os.environ.get('ORQ_BASE_URL', 'https://my.orq.ai')}/v3/router",
)

The same substitution applies to every tool that accepts a base URL, including the coding agents, chat interfaces, and frameworks under Integrations. Those pages document the managed cloud host, so replace https://my.orq.ai with the deployment hostname when configuring them.

OpenTelemetry

Exporters read the endpoint from the environment. Point it at the deployment host:

export OTEL_EXPORTER_OTLP_ENDPOINT="$ORQ_BASE_URL/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $ORQ_API_KEY"

Exporters that require the full signal path use $ORQ_BASE_URL/v2/otel/v1/traces. See the Observability quickstart for the full exporter setup.

Troubleshooting

Requests reach the managed cloud instead of the deployment. The base URL was not applied. In Node.js, confirm the option is spelled serverURL and not serverUrl. In Python, confirm server_url is passed to the Orq constructor rather than to the individual method call. When the option is missing or misspelled the SDKs fall back to the host published in the OpenAPI specification, https://api.orq.ai, so calls succeed against the managed cloud instead of failing outright.

On-Prem Requirements

Infrastructure requirements for deploying Orq.ai on-premise, including the DNS record and TLS certificate for the platform hostname.

Orq SDK

Terminal & Agents

Terraform

Platform APIs

Management APIs

Base URLs

Base URLs

Orq SDKs

AI Gateway

OpenTelemetry

Troubleshooting

On-Prem Requirements

​Base URLs

​Orq SDKs

​AI Gateway

​OpenTelemetry

​Troubleshooting

On-Prem Requirements

Base URLs

Orq SDKs

AI Gateway

OpenTelemetry

Troubleshooting