Override a Server's Base URL - Caylex Developer Docs

Servers generated in the Server Foundry are created with a single default base URL (the upstream API they call). Sometimes one customer/project needs the same generated server to talk to a different upstream host — for example a per-tenant subdomain or a staging environment. That’s a base URL override: it lives on the server instance (the project’s copy of the server), so each project can point at its own upstream without regenerating or forking the server. This recipe walks through the common flow:

Resolve a project ID (by name or from a known UUID).
List the project’s server instances and pick the Foundry server to override.
Set the override on that instance (or clear it to fall back to the default).

Overrides apply to Foundry-generated servers only (server_type = foundry). Setting one on an external or catalog server returns 400. All endpoints require admin access and operate at tenant scope, so a platform access token can read and update any instance in your workspace.

At tool-call time the override is forwarded to the running server, which swaps its baked-in default base URL for your value. It only rewrites calls that target the default base URL — if the server was generated with multiple base URLs (per-endpoint routing), endpoints pinned to a different host keep theirs.

Endpoints used

Method & path	Purpose
`GET /api/v1/projects/search`	Find a project by name (targeted, server-side search).
`GET /api/v1/server-instances`	List server instances; filter by `project_id`.
`PATCH /api/v1/server-instances/{server_instance_id}/base-url-override`	Set or clear the per-instance base URL override.

Resolve the project ID

If you already have a project ID, skip this step. GET /api/v1/projects/search?search={name} does a case-insensitive partial match on project name/description and returns paginated results — pick the exact name from items (usually just one).

{
  "items": [
    {
      "id": "7e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
      "name": "Acme Corp",
      "description": "Production deployment for Acme",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": { "size": 20, "total": 1, "has_next": false, "has_prev": false }
}

List the project’s server instances

GET /api/v1/server-instances?project_id={id} returns the project’s instances (cursor-paginated). Each item includes the fields you need to identify and override a Foundry server:

Field	Notes
`id`	The server instance ID — the path parameter for the PATCH below.
`server_name` / `display_name`	Match your target server. `display_name` is the friendly name for Foundry servers.
`server_type`	`foundry`, `external`, or `caylex`. Only `foundry` supports overrides.
`default_base_url`	The server-level default upstream base URL (Foundry only).
`base_url_override`	The current override, or `null` when the instance uses the default.

{
  "items": [
    {
      "id": "3f9c2d10-8a4b-4e21-9f77-1c2d3e4f5a6b",
      "server_id": "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e",
      "project_id": "7e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
      "server_name": "acme-corp-platform-mcp",
      "display_name": "Acme Corp Platform MCP",
      "server_type": "foundry",
      "default_base_url": "https://api.widgets.io",
      "base_url_override": null,
      "paused": false
    }
  ],
  "meta": { "size": 20, "total": 1, "has_next": false, "next_cursor": null }
}

Set (or clear) the override

PATCH /api/v1/server-instances/{server_instance_id}/base-url-override with a JSON body:

{ "base_url_override": "https://acme.widgets.io" }

Body field	Notes
`base_url_override`	The upstream base URL for this project. Send `null` or `""` to clear it (revert to `default_base_url`).

The value must be an absolute http(s) URL with a real, routable host — placeholder hosts (e.g. example.com, localhost) and unreachable/internal hosts are rejected with 400. On success the endpoint echoes the stored (normalized) values:

{
  "server_instance_id": "3f9c2d10-8a4b-4e21-9f77-1c2d3e4f5a6b",
  "base_url_override": "https://acme.widgets.io",
  "default_base_url": "https://api.widgets.io"
}

You can also set this in the Caylex Platform UI: open the project-server side drawer and click the pencil next to Base URL. A blue dot indicates an active override.

The procedure

Resolve the project ID

GET /api/v1/projects/search?search={name} and pick the exact-name match’s id — or use a project_id you already have.

Find the Foundry server instance

GET /api/v1/server-instances?project_id={id}, then pick the item whose server_name/display_name matches your target and whose server_type is foundry. Keep its id (and note default_base_url).

Set the override

PATCH /api/v1/server-instances/{id}/base-url-override with { "base_url_override": "https://…" }.

(Optional) Clear it later

PATCH the same path with { "base_url_override": null } to revert the instance to the server default.

Full script

This resolves a project by name, finds a Foundry server instance by name within that project, and sets its base URL override. Set NEW_BASE_URL = None to clear the override instead.

Python
TypeScript
cURL

set_base_url_override.py

import os
from urllib.parse import quote

import requests

BASE_URL = "https://api.caylex.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['CAYLEX_PLATFORM_TOKEN']}"}

PROJECT_NAME = "Acme Corp"
SERVER_NAME = "Acme Corp Platform MCP"  # matches server_name or display_name
NEW_BASE_URL: str | None = "https://acme.widgets.io"  # None clears it


def get_items(path: str, params: dict | None = None) -> list[dict]:
    """Fetch a cursor-paginated list endpoint (returns all items)."""
    params = dict(params or {})
    params.setdefault("size", 100)
    items: list[dict] = []
    cursor: str | None = None
    while True:
        page_params = {**params}
        if cursor:
            page_params["cursor"] = cursor
        resp = requests.get(f"{BASE_URL}{path}", headers=HEADERS, params=page_params)
        resp.raise_for_status()
        page = resp.json()
        items.extend(page["items"])
        if not page["meta"]["has_next"]:
            break
        cursor = page["meta"]["next_cursor"]
    return items


def project_id_by_name(name: str) -> str | None:
    # Targeted server-side search (case-insensitive partial match); pick the exact name.
    matches = get_items("/projects/search", {"search": name})
    return next((p["id"] for p in matches if p["name"] == name), None)


def find_foundry_instance(project_id: str, server_name: str) -> dict | None:
    instances = get_items("/server-instances", {"project_id": project_id})
    return next(
        (
            si
            for si in instances
            if si.get("server_type") == "foundry"
            and server_name in (si.get("display_name"), si.get("server_name"))
        ),
        None,
    )


def set_base_url_override(instance_id: str, base_url: str | None) -> dict:
    resp = requests.patch(
        f"{BASE_URL}/server-instances/{quote(instance_id)}/base-url-override",
        headers=HEADERS,
        json={"base_url_override": base_url},
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    project_id = project_id_by_name(PROJECT_NAME)
    if not project_id:
        raise SystemExit(f"project not found: {PROJECT_NAME!r}")

    instance = find_foundry_instance(project_id, SERVER_NAME)
    if not instance:
        raise SystemExit(f"foundry server not found: {SERVER_NAME!r}")

    print(f"default base URL: {instance['default_base_url']}")
    print(f"current override: {instance['base_url_override']}")

    result = set_base_url_override(instance["id"], NEW_BASE_URL)
    action = "cleared" if NEW_BASE_URL is None else f"set to {result['base_url_override']}"
    print(f"override {action} (default: {result['default_base_url']})")

setBaseUrlOverride.ts

const BASE_URL = "https://api.caylex.ai/api/v1";
const AUTH = { Authorization: `Bearer ${process.env.CAYLEX_PLATFORM_TOKEN}` };

const PROJECT_NAME = "Acme Corp";
const SERVER_NAME = "Acme Corp Platform MCP"; // matches server_name or display_name
const NEW_BASE_URL: string | null = "https://acme.widgets.io"; // null clears it

async function getItems(path: string, params: Record<string, string> = {}) {
  const items: any[] = [];
  let cursor: string | null = null;
  do {
    const qs = new URLSearchParams({ ...params, size: "100" });
    if (cursor) qs.set("cursor", cursor);
    const res = await fetch(`${BASE_URL}${path}?${qs}`, { headers: AUTH });
    if (!res.ok) throw new Error(`GET ${path} failed: ${res.status}`);
    const page = await res.json();
    items.push(...page.items);
    cursor = page.meta.has_next ? page.meta.next_cursor : null;
  } while (cursor);
  return items;
}

async function projectIdByName(name: string) {
  // Targeted server-side search (case-insensitive partial match); pick the exact name.
  const matches = await getItems("/projects/search", { search: name });
  return matches.find((p) => p.name === name)?.id as string | undefined;
}

async function findFoundryInstance(projectId: string, serverName: string) {
  const instances = await getItems("/server-instances", { project_id: projectId });
  return instances.find(
    (si) =>
      si.server_type === "foundry" &&
      [si.display_name, si.server_name].includes(serverName),
  );
}

async function setBaseUrlOverride(instanceId: string, baseUrl: string | null) {
  const res = await fetch(
    `${BASE_URL}/server-instances/${encodeURIComponent(instanceId)}/base-url-override`,
    {
      method: "PATCH",
      headers: { ...AUTH, "Content-Type": "application/json" },
      body: JSON.stringify({ base_url_override: baseUrl }),
    },
  );
  if (!res.ok) throw new Error(`PATCH override failed: ${res.status}`);
  return res.json();
}

const projectId = await projectIdByName(PROJECT_NAME);
if (!projectId) throw new Error(`project not found: ${PROJECT_NAME}`);

const instance = await findFoundryInstance(projectId, SERVER_NAME);
if (!instance) throw new Error(`foundry server not found: ${SERVER_NAME}`);

console.log(`default base URL: ${instance.default_base_url}`);
console.log(`current override: ${instance.base_url_override}`);

const result = await setBaseUrlOverride(instance.id, NEW_BASE_URL);
const action = NEW_BASE_URL === null ? "cleared" : `set to ${result.base_url_override}`;
console.log(`override ${action} (default: ${result.default_base_url})`);

BASE="https://api.caylex.ai/api/v1"
AUTH="Authorization: Bearer $CAYLEX_PLATFORM_TOKEN"

# 1. Find the project by name (targeted search; pick the exact match from items[])
curl -G "$BASE/projects/search" -H "$AUTH" --data-urlencode "search=Acme Corp"

PROJECT_ID="7e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b"

# 2. List the project's server instances; find the foundry one you want
#    and copy its "id" (and note "default_base_url" / "base_url_override").
curl -G "$BASE/server-instances" -H "$AUTH" \
  --data-urlencode "project_id=$PROJECT_ID" \
  --data-urlencode "size=100"

INSTANCE_ID="3f9c2d10-8a4b-4e21-9f77-1c2d3e4f5a6b"

# 3. Set the override for this project's instance
curl -X PATCH "$BASE/server-instances/$INSTANCE_ID/base-url-override" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"base_url_override": "https://acme.widgets.io"}'

# 4. Clear it later (revert to the server default)
curl -X PATCH "$BASE/server-instances/$INSTANCE_ID/base-url-override" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"base_url_override": null}'

The full request and response schema for these endpoints is browsable in the interactive API reference at https://developers.caylex.ai.

Next steps

Provision a customer project

Stand up a project per customer, then point its Foundry servers at customer-specific upstreams.

Copy tool permissions

Replicate tool permission settings across server instances.

Platform Authentication

Create and manage the platform access token these recipes use.

REST API Reference

Full request/response schemas for these endpoints.

​Endpoints used

​Resolve the project ID

​List the project’s server instances

​Set (or clear) the override

​The procedure

​Full script

​Next steps

Provision a customer project

Copy tool permissions

Platform Authentication

REST API Reference

Endpoints used

Resolve the project ID

List the project’s server instances

Set (or clear) the override

The procedure

Full script

Next steps