CometAPI model IDs for operators
Last reviewed: 2026-05-11
Who this is for: platform engineers, SREs, and integration owners who need to maintain a dependable list of CometAPI model identifiers used by production applications.
For related implementation notes, start with the CometAPI tutorials index and the tutorial posts archive. If you are publishing an internal variant of this runbook, check the editorial guidance for site conventions.
Key takeaways
- Treat the CometAPI models endpoint documentation as the contract source, not an inferred OpenAI-compatible pattern.
- Store model identifiers exactly as returned or documented; do not lowercase, trim, alias, or rewrite them unless your own registry explicitly maps aliases.
- A model appearing in a catalog response should not be treated as proof that it is approved for your workload, budget, latency target, or downstream endpoint.
- Build a model-ID registry with owner, use case, validation date, and rollback contact.
- Use catalog diffs for change awareness, not automatic production model switching.
- Verify rate-limit, billing, and error-response behavior against the documented contract and your account terms before scheduling automated polling.
Concise definition
The models endpoint is the API contract you use to inspect available model identifiers for a CometAPI integration. A model identifier is the exact string your application later passes as a model value to a supported inference endpoint. This runbook focuses on identifier governance and endpoint validation, not model benchmarking or vendor ranking.
The source checked for this draft is the CometAPI API documentation page for API 13851471: https://apidoc.cometapi.com/api-13851471.
Contract details to verify
Use this table before writing automation. Record the verified values in your internal integration repository so future operators do not need to reverse-engineer behavior from application logs.
| Contract area | What to verify | Operator acceptance criteria | Source or support |
|---|---|---|---|
| Endpoint paths | Confirm the documented HTTP method, base URL, and path for listing models. If using a path such as GET /v1/models, verify it directly against the CometAPI documentation and your environment before deployment. | Base URL and path are stored separately in configuration. No hard-coded preview, staging, or personal test URL is committed. | CometAPI API documentation: API 13851471, plus an authenticated staging request. |
| Auth headers | Confirm the required authentication header format, such as a bearer-token Authorization header if shown by the documentation. | The API key is loaded from secret storage. Logs never include the key or full header value. | CometAPI API documentation: API 13851471, plus your secret-management policy. |
| Request fields | Check whether the models-list request accepts no body, query parameters, pagination parameters, or filters. | The inventory job sends only documented fields. Undocumented request bodies are rejected in code review. | CometAPI API documentation: API 13851471. |
| Response fields | Confirm the top-level response shape and the field that contains each model identifier, commonly an id-like string in model-list APIs. | Parser requires only fields your workflow needs, tolerates additive fields, and fails visibly if the identifier field is missing. | CometAPI API documentation: API 13851471, plus captured staging response samples. |
| Error behavior | Verify status codes and response bodies for invalid key, missing key, wrong path, unsupported method, and malformed request. | Runbook maps each observed class to an action: fix credentials, fix config, retry later, or escalate. | Documentation if listed on API 13851471; otherwise support with your own negative tests. |
| Rate-limit or billing assumptions | Confirm whether catalog polling has rate limits, quota impact, or billing implications. Do not assume it is free or unlimited unless your source says so. | Polling interval is conservative, configurable, and approved by the account owner. | Not established by this article alone. Verify in CometAPI documentation, account terms, billing dashboard, or support response before automation. |
Validation runbook
1. Capture the contract before coding
Open the CometAPI documentation page for the endpoint and record:
- HTTP method.
- Base URL and path.
- Required headers.
- Whether a request body is allowed.
- Response example and required identifier field.
- Documented error codes, if present.
- Any pagination, filtering, or limit parameters, if present.
Commit this as a small contract note near the integration code, for example docs/cometapi-models-contract.md. Include the review date and the evidence URL.
2. Run one authenticated read from a controlled environment
Use a staging or low-risk key. Replace the base URL only after confirming it against the documentation.
COMETAPI_BASE_URL="https://api.cometapi.com"
curl -sS --fail-with-body \
-H "Authorization: Bearer ${COMETAPI_API_KEY}" \
-H "Accept: application/json" \
"${COMETAPI_BASE_URL}/v1/models"
Practical pass conditions to tune for your environment:
- The request returns a successful HTTP status.
- The response is JSON.
- The response contains a collection of model records.
- Each record you plan to use exposes a stable identifier field.
- The command output contains no credentials in shell history, CI logs, or observability traces.
If any of those fail, do not compensate in application code first. Re-check the documented contract, base URL, environment, and API key scope.
3. Normalize only for comparison, never for execution
For drift detection, it is reasonable to sort model IDs before comparing snapshots. For execution, keep the exact identifier string.
Recommended handling:
- Preserve case.
- Preserve punctuation.
- Preserve provider or family prefixes if present.
- Do not replace
/,:,.,_, or-unless your own registry explicitly defines a separate alias. - Do not use display names as executable IDs unless the documentation says they are accepted.
A safe internal registry row can look like this:
| Field | Example value | Why it matters |
|---|---|---|
model_id | exact-id-from-response | The string passed to downstream API calls. |
owner_team | support-automation | Someone must approve changes. |
approved_endpoint | chat-completions | Catalog presence alone does not prove endpoint compatibility. |
last_validated_at | 2026-05-11 | Prevents stale approvals. |
validation_method | models-endpoint-read + endpoint-specific canary | Shows how the ID was checked. |
rollback_model_id | previous-approved-id | Keeps rollback explicit, not automatic. |
4. Build catalog drift checks as inventory, not failover
A models endpoint is useful for detecting catalog changes, but it should not be the only signal that changes production traffic.
A practical drift workflow:
- Fetch the model catalog on a schedule approved by your account owner.
- Extract only the identifier field and any metadata your policy uses.
- Sort the identifiers.
- Compare against the previous snapshot.
- Classify changes as added, removed, or metadata-changed.
- Create a ticket or low-priority alert for review.
- Require endpoint-specific validation before adding a new ID to production allowlists.
Example thresholds are environment-specific. For many teams, a daily or weekly inventory job is enough; high-frequency polling should be justified by a real operational need and checked against rate-limit or billing terms.
5. Gate production model changes
Before a model ID becomes production-eligible, require:
- Documentation contract reviewed against CometAPI API 13851471.
- Model ID captured exactly from the documented or observed catalog.
- Endpoint-specific test run for the workload that will use it.
- Budget or quota owner approval where applicable.
- Observability labels updated to include the model ID.
- Rollback plan recorded.
- Application configuration deployed through normal change management.
This avoids a common failure mode: assuming that “listed” means “ready for this application.”
6. Handle common failures by class
Verify exact status codes and response bodies in your environment. The actions below are operational patterns, not universal guarantees.
| Failure class | Likely meaning | First operator action |
|---|---|---|
| Authentication failure | Missing, expired, malformed, or unauthorized key. | Check secret source, key scope, and header construction. Do not print the key while debugging. |
| Not found or method not allowed | Wrong base URL, path, method, or environment. | Compare request line against the documented endpoint. |
| Schema mismatch | Parser expects fields not present in the response. | Inspect the current documented response and update contract tests before changing production parsing. |
| Rate-limit response | Polling too often or account limit reached. | Back off, reduce schedule, and verify account terms. |
| Server-side or network error | Temporary service, routing, DNS, or proxy issue. | Retry with bounded backoff; escalate if repeated. |
| Empty or unexpected catalog | Account scope, region, permission, or contract difference. | Do not remove production IDs automatically; open an investigation. |
Practical validation steps for CI
Add a lightweight contract job that can run manually or on a safe schedule.
Minimum checks:
COMETAPI_API_KEYexists only in secret storage.- Request URL is built from configured base URL plus documented path.
- Request sends documented auth headers.
- Response parses as JSON.
- Identifier list extraction succeeds.
- Approved production IDs are still present, if catalog semantics support that check.
- Unknown new IDs are reported but not automatically enabled.
- Removed IDs create a review ticket rather than immediate traffic migration.
Avoid storing full response bodies if they may contain account-specific metadata. Store a sanitized snapshot containing only the fields your registry needs.
Sources checked
| Source | Access date | Purpose | Notes |
|---|---|---|---|
| CometAPI API documentation, API 13851471 | 2026-05-11 | Primary evidence for the models endpoint contract to verify: method, path, authentication, request shape, and response shape. | Use the live documentation as the final source before implementation. This draft does not claim pricing, availability, benchmark, or billing behavior. |
FAQ
Can I use every returned model ID in production?
No. Treat the catalog as discovery, not approval. A production model ID should also pass endpoint-specific validation, ownership review, budget review, and rollback planning.
Should I lowercase model identifiers for consistency?
No. Store and send model identifiers exactly as documented or returned. Lowercasing or rewriting IDs can turn a valid identifier into an invalid one.
Is the models endpoint enough to prove chat-completion compatibility?
No. A catalog response can tell you what identifiers are visible through the models contract, but you should run a separate endpoint-specific canary for the API surface your application actually uses.
How often should I poll the models endpoint?
Use a conservative interval and tune it to operational need. Daily or weekly inventory is often sufficient for governance workflows, but you must verify any rate-limit, quota, or billing assumptions against your account terms and documentation.
What should happen if an approved model disappears from the catalog?
Do not automatically switch production traffic based only on the catalog diff. Create an incident or review ticket, check whether existing traffic is affected, validate the documented contract, and contact the responsible account or platform owner.
Where should model IDs live in application code?
Prefer configuration or an internal model registry over scattered string literals. Each approved ID should have an owner, validation date, intended endpoint, and rollback plan.