Last reviewed: 2026-06-12
Direct answer
When writing or updating a tutorial that describes how a coding agent calls CometAPI, run a source evidence check before each API contract claim. A source evidence check means: load the current CometAPI docs page that covers the claim, confirm the endpoint path exists and responds, verify the auth header format matches what the docs describe, and check request and response field names against a live example request. Record the docs URL, access date, and the specific field or behavior you confirmed before embedding that claim in your tutorial.
The two highest-risk endpoint families to check are the chat completions endpoint and the responses endpoint, both documented at apidoc.cometapi.com. Exact endpoint paths, accepted fields, auth header names, and response envelope shapes must be verified from the current docs each time. Use placeholder wording in your draft for any claim you have not yet verified from a current source URL, and do not promote a placeholder to an assertion without a backing source.
Verify Coding Agent Outputs Before They Ship covers a general output-verification workflow for coding agent sessions; this article focuses on the CometAPI API contract areas that carry the highest tutorial risk.
For broader release checks, see Agent Run Evidence Ledgers for Human Review .
Who this is for
- Tutorial authors writing step-by-step guides for coding agents that call CometAPI endpoints
- Agent operators who maintain AGENTS.md or CLAUDE.md instruction files that embed API request patterns
- Teams running automated tutorial pipelines where API contract claims may drift between publication cycles
If your tutorial embeds endpoint paths, auth header patterns, request field names, or response field names sourced from CometAPI documentation, the evidence checks in this guide apply directly to your work.
Key takeaways
- Run source evidence checks for every CometAPI API contract claim before publication. Do not carry forward assumptions from earlier articles or drafts.
- Check endpoint paths, auth header format, required request fields, and response envelope fields from the current docs before drafting tutorial copy.
- Keep a short log record for each verified claim: docs URL, access date, field or behavior confirmed, and the safe wording used in the draft.
- Use placeholder wording for any claim not yet verified from a current source URL. Do not promote placeholders to assertions without a source.
- If docs behavior is unclear or a field is undocumented, keep that area marked for verification and link to the CometAPI help center for escalation.
- Instruction files such as AGENTS.md and CLAUDE.md can encode source-check steps so coding agents run evidence checks before embedding API claims into new tutorial content.
Smoke-test workflow
This workflow assumes you have a valid CometAPI API key stored in an environment variable (never hard-code credentials), and that you have confirmed the base URL from the current CometAPI docs root before building any request.
Setup assumptions
- API key stored in an environment variable such as COMETAPI_API_KEY. Do not hard-code key values in tutorial examples or log records.
- Base URL read from the current CometAPI docs. Do not use a base URL you have not confirmed from the current docs root at apidoc.cometapi.com.
- Endpoint path and required request fields read from the chat completions docs page or the responses docs page before you build the request. Exact paths and field names must come from the docs, not from memory.
Happy-path request plan
Send a minimal well-formed request to the chat completions endpoint using the request schema described in the current docs. Use a short, clearly synthetic prompt so the request is identifiable in logs. Record the HTTP status code, the top-level response field names observed, and the access timestamp. Confirm that the status and field names match what the docs describe.
Error-path check
Send the same minimal request with an intentionally invalid API key. Confirm the response returns an error status and an error body. Record the status code and the top-level error field names. This confirms your tutorial’s error-handling guidance is grounded in actual gateway behavior rather than assumed behavior.
Minimum assertions
- Happy-path response status matches the success status documented in the current docs.
- Error-path response status matches the error status documented in the current docs or help center.
- Response envelope includes the top-level fields described in the docs for the endpoint family tested.
What the smoke test must not assert
Do not assert specific model identifiers, pricing figures, usage quota values, rate-limit header names, or latency targets unless the current docs directly state those values for the endpoint you tested. Link readers to the relevant docs pages for those areas rather than embedding them as tutorial assertions.
Sanitized log-record template
smoke_test_log: endpoint_family: “[chat_completions|responses]” docs_url: “” accessed_at: “” http_status_happy: “” http_status_error: “” response_fields_observed: ["", “”] error_fields_observed: [""] safe_claim_used: “” verified_by: “”
Do not record real API keys, full response bodies, real prompts, or production model outputs in this log.
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
- OpenAI Codex AGENTS.md guidance - accessed 2026-06-12; purpose: verify repository instruction-file context for coding agents.
- Claude Code memory documentation - accessed 2026-06-12; purpose: verify project memory and instruction-file context for agent workflows.
- CometAPI documentation - accessed 2026-06-12; purpose: verify current CometAPI documentation navigation.
- CometAPI chat completions reference - accessed 2026-06-12; purpose: verify chat completion contract areas.
- CometAPI responses reference - accessed 2026-06-12; purpose: verify responses endpoint contract areas.
- CometAPI help center - accessed 2026-06-12; purpose: verify support and escalation documentation areas.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Chat completions endpoint path | Confirm the full endpoint path from the current docs before embedding in tutorial copy | https://apidoc.cometapi.com/api/text/chat | 2026-06-12 | “Send a POST request to the chat completions path described in the current CometAPI chat docs.” |
| Auth header name and format | Confirm the exact header name and token format from the current docs | https://apidoc.cometapi.com/api/text/chat | 2026-06-12 | “Include the authorization header as described in the CometAPI chat docs.” |
| Chat completions required request fields | Confirm which fields are required vs. optional in the current docs | https://apidoc.cometapi.com/api/text/chat | 2026-06-12 | “Include the required request fields listed in the current CometAPI chat completions docs.” |
| Chat completions response envelope | Confirm top-level response field names from the current docs | https://apidoc.cometapi.com/api/text/chat | 2026-06-12 | “The response includes the fields documented in the CometAPI chat completions reference.” |
| Responses endpoint path | Confirm the full endpoint path from the current docs before embedding in tutorial copy | https://apidoc.cometapi.com/api/text/responses | 2026-06-12 | “Send a request to the responses path described in the current CometAPI responses docs.” |
| Responses endpoint required request fields | Confirm required and optional fields from the current docs | https://apidoc.cometapi.com/api/text/responses | 2026-06-12 | “Include the fields required by the CometAPI responses endpoint as listed in the current docs.” |
| Escalation path for undocumented behavior | Confirm the current support URL for contract gaps or ambiguous fields | https://apidoc.cometapi.com/support/help-center | 2026-06-12 | “If a contract area is unclear, refer to the CometAPI help center for current guidance.” |
| AGENTS.md instruction-file read scope | Confirm that AGENTS.md rules are read by the agent before tool calls in the Codex environment | https://github.com/openai/codex/blob/main/docs/agents_md.md | 2026-06-12 | “Add source-check steps to AGENTS.md so the agent runs them before embedding API claims.” |
| CLAUDE.md and project-memory scope | Confirm that CLAUDE.md and project memory files govern Claude Code agent behavior | https://code.claude.com/docs/en/memory | 2026-06-12 | “Add source-check steps to CLAUDE.md so Claude Code agents apply them during drafting.” |
Reader next step
Compare the workflow against Start with CometAPI .
Use Agent Run Evidence Ledgers for Human Review as the next comparison point. Keep When to Stop, Retry, or Escalate: A Practical Guide to Coding Agent Task Control nearby for setup and permission checks.
FAQ
Why do I need to re-check CometAPI sources for every new tutorial draft?
API documentation changes between publication cycles. An endpoint path, a required field, or an auth header format that was accurate in a prior article may differ in the current docs. Running a fresh source check for each draft prevents your tutorial from embedding stale contract claims that could break an operator’s integration.
Where should I store my verified source evidence?
Record the docs URL, access date, and the confirmed field or behavior in a short log entry attached to your draft. See the sanitized log-record template in the smoke-test workflow section above. Do not store API keys, full response bodies, or real prompts in that record.
Can I add source-check steps to my agent instruction files?
Yes. AGENTS.md (used by Codex-based agents) and CLAUDE.md or project memory files (used by Claude Code) accept rules that fire before the agent takes action. You can add an instruction telling the agent to load the relevant CometAPI docs URL and confirm the endpoint path before it embeds any API contract claim in a draft. See How to Write Repository Instructions for Coding Agents for guidance on structuring instruction files for these kinds of pre-action checks.
What if a CometAPI docs page is unreachable when I try to access it?
If a source URL is unreachable, do not substitute a cached or assumed version of the contract. Note the access failure in your log record and treat the affected claim as unverified. Use placeholder wording in your draft and link to the CometAPI help center so readers can verify that area themselves.
How do I handle CometAPI contract areas not covered in the public docs?
If a contract area is undocumented or ambiguous, keep it in a to-verify state in your draft and do not promote it to an assertion. Link to the CometAPI help center for escalation. This prevents reader-facing copy from embedding claims that cannot be backed by a source.
Does this workflow apply to agent-generated drafts as well as human-authored ones?
Yes. When a coding agent generates or revises tutorial content, the same source evidence checks apply. Embedding check steps in the agent’s instruction file makes the evidence gate part of the automated workflow rather than a manual post-processing step. See How Agent Guides Fail Without Source Backing: A Field-Level Breakdown for the most common patterns that occur when source checks are skipped.
Start with CometAPI