API field naming: 14 paths use camelCase while OpenAI-compat endpoints use snake_case; billing requires stripped UUIDs

[Evrard-Nil]

Summary

The cloud-api has two inconsistent naming/identifier conventions, depending on which endpoint family you're hitting:

1. camelCase vs snake_case

Convention	Endpoints	Example fields
snake_case	OpenAI-compat: /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/files, /v1/audio/*, /v1/images/*, /v1/rerank, /v1/conversations, ...	prompt_tokens, tool_calls, finish_reason, created_at, system_fingerprint
camelCase	/v1/admin/*, /v1/billing/*, /v1/services/*, /v1/workspaces/*, /v1/model/{model_name}	requestIds, costPerImage, cacheReadCostPerToken, createdAt, isActive, displayName, spendLimit

Per the OpenAPI spec, 114 distinct camelCase fields appear across 14 paths. Clients porting from OpenAI conventions (or using snake_case-by-default JSON serializers) hit unexpected missing field errors on the admin/billing side.

2. Identifier prefix mismatch

The id field returned in chat completion responses includes a chatcmpl- prefix:

{"id":"chatcmpl-d53bfb7d-8eb3-4750-bd90-94a1365f906c", ...}

But /v1/billing/costs expects the stripped UUID (no prefix):

# WRONG — uses the same id from the response
curl -s -X POST https://cloud-api.near.ai/v1/billing/costs \
  -d '{"requestIds":["chatcmpl-d53bfb7d-8eb3-4750-bd90-94a1365f906c"]}'
# HTTP 422 "UUID parsing failed: invalid character: found `h` at 2"

# CORRECT — strip the prefix
curl -s -X POST https://cloud-api.near.ai/v1/billing/costs \
  -d '{"requestIds":["d53bfb7d-8eb3-4750-bd90-94a1365f906c"]}'
# HTTP 200 {"requests":[{"requestId":"...","costNanoUsd":0}]}

A user looking up costs for chat IDs they've kept track of must know to strip the prefix — undocumented.

Suggested fix

Naming:

• Pick one convention per surface and stick to it. If the admin/billing/services surfaces are considered private (UI-internal), document them that way. If they're part of the public OpenAPI, normalize to snake_case to match the rest.
• Alternative: serde-rename camelCase fields to snake_case in the JSON layer while keeping the internal Rust struct camelCase. Single source of truth.

Identifiers:

• Either accept chatcmpl- prefix on billing lookups, OR strip the prefix in response IDs. The mismatch is the bug.
• Either way, document the format clearly in the OpenAPI description.

Notable affected admin/billing paths

/v1/admin/models, /v1/admin/models/{model_name}, /v1/admin/models/deprecate,
/v1/admin/organizations/{org_id}/concurrent-limit,
/v1/admin/organizations/{org_id}/limits,
/v1/admin/services, /v1/admin/services/{id},
/v1/billing/costs, /v1/model/{model_name},
/v1/services/{service_name},
/v1/workspaces/{workspace_id}/api-keys,
/v1/workspaces/{workspace_id}/api-keys/{key_id},
/v1/workspaces/{workspace_id}/api-keys/{key_id}/spend-limit

---

Found during routine cloud-api smoke test.

[Evrard-Nil]

Related finding from continued smoke testing — model-name casing conventions are mixed in /v1/models:

catalog count: 40
  nearai:    Qwen/Qwen3-30B-A3B-Instruct-2507     (PascalCase)
  nearai:    Qwen/Qwen3.5-122B-A10B                (PascalCase)
  nearai:    zai-org/GLM-5.1-FP8                   (kebab-PascalCase)
  qwen:      qwen/qwen3.7-max                      (all lowercase!)
  moonshotai: moonshotai/kimi-k2.6                 (all lowercase)
  anthropic: anthropic/claude-haiku-4-5            (all lowercase)
  openai:    openai/gpt-oss-120b                   (all lowercase)
  google:    google/gemma-4-31B-it                 (mixed: lowercase google, PascalCase-ish gemma)

So Qwen self-hosted models follow upstream HF Hub casing, but the new qwen/qwen3.7-max passthrough uses all lowercase. Even within a single org (google/gemini-2.5-flash lowercase vs google/gemma-4-31B-it PascalCase), the convention isn't uniform.

Plus model-name lookup has inconsistent case-handling:

# Canonical PascalCase — works
curl ... -d '{"model":"Qwen/Qwen3-30B-A3B-Instruct-2507", ...}'    # HTTP 200

# Full lowercase — works (response.model returns canonical PascalCase)
curl ... -d '{"model":"qwen/qwen3-30b-a3b-instruct-2507", ...}'    # HTTP 200

# Mixed case — fails
curl ... -d '{"model":"qwen/Qwen3-30B-A3B-Instruct-2507", ...}'    # HTTP 400 not found
curl ... -d '{"model":"QWEN/qwen3-30b-a3b-instruct-2507", ...}'    # HTTP 400 not found

So all-lowercase is treated as an alias to canonical, but mixed-case isn't normalized. Either:

• Make the model-name lookup fully case-insensitive (and document it), or
• Reject all non-exact matches (drop the all-lowercase alias).

The current state means a user copy-pasting from the catalog or a typo on capitalization randomly succeeds or fails depending on what they hit.

Side note: the two new models (moonshotai/kimi-k2.6 and qwen/qwen3.7-max) both work correctly as passthroughs (~3-5s response time, return reasoning content).

[Evrard-Nil]

Related — cost lookups via /v1/billing/costs are blocked for passthrough providers because their request IDs aren't UUIDs:

# Self-hosted (gpt-oss-120b): id is `chatcmpl-<uuid>`
ID="chatcmpl-76b5e1a6-f533-4cb0-8ea3-0664069f651e"
UUID=${ID#chatcmpl-}
curl -s -X POST -d "{\"requestIds\":[\"$UUID\"]}" .../v1/billing/costs
# {"requests":[{"requestId":"76b5...","costNanoUsd":0}]}   ← works (strip prefix)

# Anthropic passthrough: id is `msg_017yn...` (not UUID-shaped)
ID="msg_017ynTCvHtaoYsRt2CHqRZKK"
UUID=${ID#msg_}
curl -s -X POST -d "{\"requestIds\":[\"$UUID\"]}" .../v1/billing/costs
# HTTP 422
# Failed to deserialize the JSON body into the target type: requestIds[0]: UUID parsing failed: invalid character: found `y` at 4

So a user tracking cost across their full conversation history cannot query Anthropic-routed messages via /v1/billing/costs. Either:

• billing tracking isn't done for passthrough calls (in which case the endpoint should say so), or
• the IDs need to be normalized to a single internal format that's UUID-shaped across providers.

(Also: gpt-oss-120b cost consistently returns costNanoUsd: 0 even after waiting 15+ seconds for tracking to settle. May be the test key being on a no-charge tier — there's no way to introspect from the user side. /v1/check_api_key returns only {"valid":true} with no tier info.)