The base URL shape checklist: /v1, trailing slashes, and double paths

#tutorial #api #webdev #ai

Disclosure and availability: DaoXE is a multi-model multi-protocol API gateway we operate. Public base: https://daoxe.com/v1. Not available in mainland China. This article is for developers in regions allowed by the service terms.

Most gateway failures I see are not model quality.

They are path join bugs.

The host is reachable. The key works in curl. The client still hits 404.

This post is the base URL checklist I run before blaming the API.

Series

What “OpenAI-compatible base” usually means

Many clients expect a root like:

https://daoxe.com/v1

They then append:

/chat/completions
/models
/embeddings

So the final path becomes:

https://daoxe.com/v1/chat/completions

If you already put /chat/completions in the base, or you omit /v1 when the client does not add it, you get nonsense paths.

Failure table

Setting	Final path symptom	Fix
Base missing `/v1` when client expects full OpenAI base	404 on `/chat/completions` at host root	use `https://daoxe.com/v1`
Base already ends with `/v1` and client adds `/v1/...`	`/v1/v1/chat/completions`	drop one `/v1` per client docs
Trailing slash quirks	intermittent join bugs	pick one style; retest with curl to the exact URL the client logs
Docs host ≠ live API host	wrong environment	use the live API host from the product, not a blog screenshot

Verify with curl to the exact joined URL

Do not only test “the host is up.”

Test the same path the client will call:

export DAOXE_API_KEY="your_api_key"
export DAOXE_BASE_URL="https://daoxe.com/v1"
export DAOXE_MODEL="paste_exact_id_from_models"

curl --fail-with-body --show-error --silent \
  -H "Authorization: Bearer $DAOXE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$DAOXE_MODEL\",
    \"max_tokens\": 8,
    \"messages\": [{\"role\":\"user\",\"content\":\"OK\"}]
  }" \
  "$DAOXE_BASE_URL/chat/completions"

If that is green and the client is red, log the client’s request URL. Compare character-for-character.

Client-specific mental model

Client says	Often means
“OpenAI base URL”	include `/v1`
“API host”	sometimes host only; client adds `/v1`
“Custom provider”	check whether models.dev key implies the base