SUME_API_BASE_URL has /v1, the SDK baseUrl does not: which is right?

Both are right, for different clients. The Sume CLI reads SUME_API_BASE_URL, which defaults to https://api.sume.com/v1 and includes the version path. The TypeScript SDK's baseUrl option defaults to https://api.sume.com with no /v1. The SDK docs list that default and say nothing about adding /v1, so follow them as written.

Mixing them up points a client at the wrong URL: a CLI pointed at the bare host, or an SDK pointed at the /v1 base. The troubleshooting docs list a wrong API base as its own failure class. The environment variables and auth defaults for each are below.

What do the CLI environment variables do?

The CLI configuration page lists five. Only the first three matter for most CI jobs.

Which header does each client send?

The CLI defaults to x-api-key, and SUME_API_AUTH_MODE=bearer switches it to Authorization: Bearer for clients that prefer that form. The SDK sends x-api-key only and does not set Authorization.

The API accepts either header alone, but rejects both together with 401 unauthorized and the message Send only one API key credential. There is no precedence rule. So a gateway or fetch wrapper that adds its own Authorization on top of the SDK's x-api-key fails even though the key is right. With the CLI, set the mode once and do not add a second header through a proxy.

How do I point either client at development?

The SDK docs say to use https://api.dev.sume.com as baseUrl for development. For the CLI the base URL variable is the lever, and SUME_APP_BASE_URL falls back to the origin of SUME_API_BASE_URL when the API is not production, which is what sume login uses for the approval page.

Keys are per host: the errors page lists a key for the other host among the causes of 401 unauthorized. A production key will not work against the development API.

# CLI against production (these are the defaults)
export SUME_API_BASE_URL="https://api.sume.com/v1"
export SUME_API_AUTH_MODE="x-api-key"
sume doctor --agent --json

# The same host, checked with curl
curl https://api.sume.com/v1/me -H "x-api-key: $SUME_API_KEY"

# SDK equivalent (TypeScript): no /v1 here
# createSumeClient({ apiKey, baseUrl: "https://api.sume.com" })

What should I check first when I get a 404 or 401?

Run sume doctor --agent --json, which inspects local readiness without calling the API and shows what base URL the CLI resolved. The troubleshooting page names a wrong API base as its own failure class, and the production base is https://api.sume.com/v1.

Then call GET /v1/me with curl and the same key. If curl works and the CLI does not, the difference is the base URL or the auth mode. If neither works, the key is revoked, malformed or for the other host.

What about raw curl and other languages?

For curl, Python or anything hand-rolled, follow the API docs: the base is https://api.sume.com/v1, and every path on the API reference page includes /v1. So https://api.sume.com/v1/me is right, and https://api.sume.com/me is not a documented route.

The only unauthenticated routes are GET /v1/health, GET /v1/catalog, GET /v1/openapi.json, GET /v1/bgm/catalog, GET /v1/bgm/categories and POST /v1/bgm/pick. A 401 on any other /v1 path means the key is missing, malformed, revoked, for the other host, or sent in two headers at once.

The OpenAPI document itself lives at https://api.sume.com/reference/json, and Swagger UI at https://api.sume.com/reference. If you generate your own client from that schema, check whether the generator prefixes paths with /v1 before you set a base URL.

Print the final URL your client builds for a harmless read such as the account endpoint and compare it with https://api.sume.com/v1/me. If you see /v1/v1/me, the base already had the version and the path added it again. If you see /me, the base lacked it and the client did not add it.

Pair that with sume auth status for the CLI side and one curl for the HTTP side, and you will have isolated the base URL, the key and the header mode in three commands.