Last reviewed: 2026-06-09

Direct answer

Before routing any request to a CometAPI model in production, call the model catalog endpoint to confirm that the model ID your integration depends on is currently listed, active, and supports the capability type your workflow requires. The official catalog reference is at https://apidoc.cometapi.com/overview/models. The exact endpoint path, request format, response fields, and capability flag names must be verified there directly, because the catalog schema can change as new models are added or retired.

The validation sequence has three parts:

1. Retrieve the catalog and confirm your target model ID appears in the response.
2. Confirm the capability flags or type fields (for example, whether the model accepts chat, responses, image, or video input) match what your integration will send.
3. Run one minimal live request through the endpoint your integration will actually use — either the chat completions path or the responses path — and assert that the response structure matches your integration’s expectations before enabling production traffic.

This sequence catches the most common pre-integration failures: assuming a model ID is stable across provider updates, assuming a model supports a capability it does not, and assuming the response schema is identical between chat completions and responses endpoints.

Who this is for

This guide is for backend engineers and platform operators who are about to connect an application to CometAPI for the first time, or who are switching the model ID or endpoint path for an existing integration. It is also relevant for anyone running a regular readiness check before a deployment or model upgrade.

You should already have:

• A CometAPI API key (verify the exact auth header field name in the official docs).
• A target model ID you intend to use, taken from a recent catalog response — not hard-coded from memory or copied from an older integration.
• Access to curl or an equivalent HTTP client for running manual checks.

Key takeaways

• The model catalog is your authoritative source for which model IDs are currently available and what capability types each supports. Verify model IDs from the catalog before hard-coding them.
• Capability flags, provider routing, and model availability can change without a breaking API change on the endpoint path itself. A model that was active last week may be deprecated or renamed.
• The chat completions path and the responses path have different request and response shapes. Confirm which your integration is using and test specifically against that path before go-live.
• A smoke test for model catalog validation must confirm the catalog call succeeds and that the specific model ID appears — not just that the API key authenticates.
• Log the catalog snapshot at the time of your integration test so you have a record of which model IDs and capabilities were confirmed on that date.

For related production validation steps once you have confirmed your model selection, see Validate CometAPI Chat Completions for Production.

Smoke-test workflow

Setup assumptions

• You have a valid API key stored as an environment variable (for example COMETAPI_KEY). Never paste it into commands you will share or log.
• You are targeting either the chat completions path or the responses path — confirm the exact path from https://apidoc.cometapi.com/api/text/chat or https://apidoc.cometapi.com/api/text/responses before running tests.
• You have a target model ID taken from a recent catalog call, not from memory.

Step 1 — Catalog call (happy path)

Call the model catalog endpoint (verify the exact path at https://apidoc.cometapi.com/overview/models) with your API key. The call should return HTTP 200 and a list of model objects. Confirm your target model ID appears in the list and that its capability flags match your intended use.

Pseudocode — verify the exact path and auth header from the docs

GET /api/models Authorization: Bearer $COMETAPI_KEY

Assert:

• HTTP status is 200.
• The response body contains at least one model object.
• Your target model ID is present.
• The capability type field for that model matches your intended endpoint (chat, responses, image, video — verify field names in the docs).

Step 2 — Minimal live request (happy path)

Send a minimal, low-token request to your chosen endpoint using the confirmed model ID. Keep the prompt short and deterministic. Do not use real user data in smoke-test calls.

Pseudocode — verify field names and required params from the endpoint docs

POST /api/text/chat (or /api/text/responses) Authorization: Bearer $COMETAPI_KEY Content-Type: application/json

{ “model”: “”, “messages”: [{“role”: “user”, “content”: “Respond with the word OK only.”}], “max_tokens”: 5 }

Assert:

• HTTP status is 200.
• The response contains the expected output field (verify exact field name — choices, output, or other — from the endpoint docs).
• The model ID in the response matches the one you sent.

Step 3 — Error path check

Send a request with an invalid or deliberately absent model ID to confirm the API returns a meaningful error code and message rather than silently selecting a fallback model. Verify the exact error response shape at https://apidoc.cometapi.com/support/help-center.

Assert:

• HTTP status is 4xx (verify expected code from the docs).
• The error message field identifies the model ID issue.

What the smoke test must not assert

• Specific response latency or uptime guarantees — these are provider-level SLAs, not integration contract items.
• Exact token counts or billing amounts — verify billing fields separately if your integration depends on them.
• That a deprecated model will continue to work — confirm active status from the catalog on each test run.

Minimum pass/fail logging fields

Record these fields after each smoke-test run (see the log template below):

catalog_call_status: <http_status> model_id_found_in_catalog: <true/false> capability_match: <true/false> live_request_status: <http_status> response_field_present: <true/false> model_id_echo_match: <true/false> error_path_status: <http_status> test_date: tested_by: <operator_identifier>

Log record template

Use this template to record smoke-test results. Replace every placeholder with your actual run values. Do not log API keys, full prompts, or full responses.

smoke_test_run: date: “YYYY-MM-DD” operator: “operator-id-placeholder” catalog_endpoint: “” live_endpoint: “” model_id_under_test: “” catalog_http_status: 0 model_found: false capability_confirmed: false live_request_http_status: 0 response_shape_valid: false error_path_http_status: 0 notes: ""

Failure modes

• Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
• Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
• Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
• Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
• Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.

Sources checked

• CometAPI documentation - accessed 2026-06-09; purpose: verify current CometAPI documentation navigation.
• CometAPI models overview - accessed 2026-06-09; purpose: verify model catalog discovery guidance.
• CometAPI chat completions reference - accessed 2026-06-09; purpose: verify chat completion contract areas.
• CometAPI responses reference - accessed 2026-06-09; purpose: verify responses endpoint contract areas.
• CometAPI help center - accessed 2026-06-09; purpose: verify support and escalation documentation areas.

Contract details to verify

Reader next step

Compare the workflow against Start with CometAPI.

Use How to Smoke-test the CometAPI Chat Completion Contract as the next comparison point. Keep Review a CometAPI chat completions contract nearby for setup and permission checks.

FAQ

Do I need to call the model catalog before every request in production? No. The catalog validation step is a pre-integration check and a periodic readiness confirmation, not a per-request step. Cache the catalog response and re-validate on a schedule that matches how frequently you expect model availability to change. Verify any recommended polling interval or cache guidance in the official docs.

What if my target model ID is not in the catalog response? Do not proceed with the integration until you have confirmed the model ID. The model may be deprecated, renamed, or unavailable in your account tier. Consult the CometAPI Support / Help Center for resolution steps.

Is the chat completions path interchangeable with the responses path? No. They have different request and response shapes. Before switching between them, review both endpoint references (chat completions and responses) and update your integration’s request builder and response parser to match the target path. See also Choose between CometAPI Chat Completions and Responses for a comparison of when to use each.

Can I hard-code a model ID instead of querying the catalog? This creates risk. Model IDs can be deprecated or renamed without a breaking change to the endpoint path. Query the catalog during integration tests and store the confirmed ID in a configuration value you can update without a code deploy, so you can respond quickly if the model is retired.

Where do I find support if the catalog endpoint returns unexpected errors? Start at the CometAPI Support / Help Center. For account-specific issues, use the contact or escalation path listed there.

Where can I get started with CometAPI? Visit CometAPI to access sign-up, documentation, and product information.