Last reviewed: 2026-06-04
Direct answer
When a coding agent produces a pull request, the review step often requires multiple model calls: read the diff, explain the test failure, summarize the change, check the commit message. Without a stable gateway, those calls scatter across direct vendor endpoints, pick up stale base URLs, or silently switch model versions mid-session.
Routing all of those review calls through CometAPI gives you one stable base URL, one auth token, and a single place to see which model handled each step. The two endpoints most relevant to review workflows are the chat completions path (/api/text/chat) and the Responses path (/api/text/responses). Exact request shapes, supported fields, and current model IDs must be confirmed against the CometAPI docs before you finalize your integration — see the contract table below.
The short version of what this looks like in practice:
- Your agent opens a PR branch and posts a payload to the CometAPI chat completions endpoint with the diff as context.
- The gateway routes the request to the configured model and returns a structured completion.
- The agent posts the completion as a PR comment or review annotation.
- Subsequent review calls (test-failure explanation, lint summary) reuse the same base URL and token — no endpoint switching.
For operators already running a gateway, see Route Coding Agent Model Calls Without Endpoint Drift for the broader gateway setup pattern. This article focuses on the review-routing slice: what to send, how to thread context, and what to check before you go live.
For broader release checks, see AI Coding Agent Setup, Security, and Model Routing .
Who this is for
This guide is for:
- Engineering teams running automated or semi-automated PR review using coding agents such as Codex, Claude Sonnet 4.6, or Cursor
- Platform engineers setting up a shared model gateway for multiple agent workflows
- Operators who have already configured a gateway and want to add a review-step integration without changing existing agent code
You do not need to be an ML practitioner. You need to be comfortable with REST API calls, PR webhooks or CI scripts, and basic environment variable management.
Key takeaways
- Send review calls through a single CometAPI base URL so endpoint references stay stable as models are updated
- The chat completions endpoint (/api/text/chat) suits multi-turn review conversations; the Responses endpoint (/api/text/responses) suits structured single-turn review outputs — verify the exact contract in the docs before choosing
- Thread context by passing prior review messages in the request body rather than re-fetching the diff on each call
- Log the model identifier and request ID from every response so you can replay a review step if a later CI gate fails
- Keep the review agent outside the site or deployment runtime — it sends API calls; it does not mutate deployment state
- Verify pricing assumptions in the CometAPI pricing reference before scaling review frequency
Gateway setup assumptions
Before you wire up review routing, confirm:
- You have a CometAPI account and a valid API key stored in an environment variable (e.g. COMETAPI_KEY). Never hardcode the key.
- You know the base URL for your CometAPI integration. Verify the current base URL in the CometAPI documentation root — do not rely on a URL you copied from a prior project.
- You have chosen an endpoint family. The docs at /api/text/chat and /api/text/responses describe two different request/response shapes. Review both before committing your integration to one.
- Your CI or agent script can read environment variables at runtime. If you use GitHub Actions, confirm the secret is available in the workflow scope per the GitHub Actions documentation.
Smoke-test workflow
Run this workflow in a non-production branch before enabling review routing in CI.
Setup assumptions
- COMETAPI_KEY is set in your shell or CI environment
- You have a small test diff (under 1 000 tokens) ready
- You have confirmed the CometAPI base URL from the docs
Happy-path request plan
- Construct a minimal chat completions request with the system role set to a short review instruction and the user role containing the diff text
- Send the request to the CometAPI chat completions endpoint using curl or your HTTP client of choice
- Parse the response and confirm a non-empty choices[0].message.content field (verify the exact response shape against the docs — do not assume field names)
- Log the model identifier and a synthetic request ID
- Post the content as a draft PR comment using the GitHub pull requests API
Error-path check
- Send the same request without the Authorization header. Confirm you receive a 4xx status. Do not proceed if the endpoint returns 200 on an unauthenticated call.
Minimum assertions
- HTTP status is 200 for the authenticated call
- Response body can be parsed as JSON
- The review text field is non-empty
- The PR comment post returns a 201 from the GitHub API
Pass/fail logging fields
Log these fields after each smoke-test run. Use placeholder values here; replace them with real runtime values in your integration:
smoke_test_log: run_id: “” endpoint_family: “<chat|responses>” http_status: “<200|4xx|5xx>” response_parseable: “<true|false>” review_field_non_empty: “<true|false>” pr_comment_status: “<201|error>” model_id_in_response: “” notes: “”
What the smoke test must not assert
- Do not assert specific token counts, latency targets, or uptime guarantees
- Do not assert that a particular model ID is returned — model availability can change; verify current model IDs in the CometAPI models overview
- Do not assert pricing or billing field values
Connecting review routing to your PR workflow
The GitHub pull requests documentation covers the PR API surface your agent will interact with. The relevant integration points are:
- Pull request review comments: post line-level annotations using the Reviews API
- Issue comments: post a summary comment on the PR thread
- Status checks: update a commit status to reflect whether the agent review passed
For agents that follow an AGENTS.md instruction file (as described in the OpenAI Codex AGENTS.md reference), you can add a review_routing section to the instruction file that specifies which endpoint family to use, which model alias to request, and which PR fields to include in the review context.
Keep the routing configuration in the instruction file or environment variables. Do not hardcode endpoint paths in the agent’s core logic — that is what creates endpoint drift over time.
Context threading across review steps
A PR review often involves more than one model call:
- Summarize the diff
- Explain the failing test in the context of the diff
- Check the commit message against the team convention
- Produce a final pass/fail verdict
Each step should receive the prior step’s output as a prior message in the request body, not as a re-fetched diff. This keeps token usage proportional and avoids situations where the second call contradicts the first because it saw slightly different context.
The chat completions endpoint (/api/text/chat) is designed for multi-turn conversations and is the natural fit for chained review steps. The Responses endpoint (/api/text/responses) is better suited to single-turn structured outputs. Verify the exact threading mechanism for each endpoint in the CometAPI docs before deciding.
What not to route through the review gateway
Not every agent action belongs in the review routing path:
- Deployment triggers: the agent should post a review comment, not trigger a deploy
- Secret reads: the review agent should receive a sanitized diff, not raw environment files
- Repo mutations: review routing is read-and-comment only; branch creation, force-pushes, and merge actions belong in a separate, explicitly permissioned agent scope
For the broader permission and scope boundary discussion, see Set Safe Permission and Secret Boundaries for Coding Agents.
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-04; purpose: verify repository instruction-file context for coding agents.
- GitHub pull requests documentation - accessed 2026-06-04; purpose: verify pull request review and collaboration boundaries.
- CometAPI documentation - accessed 2026-06-04; purpose: verify current CometAPI documentation navigation.
- CometAPI chat completions reference - accessed 2026-06-04; purpose: verify chat completion contract areas.
- CometAPI responses reference - accessed 2026-06-04; purpose: verify responses endpoint contract areas.
- CometAPI models overview - accessed 2026-06-04; purpose: verify model catalog discovery guidance.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Chat completions request shape | Required fields, message role names, model parameter name | https://apidoc.cometapi.com/api/text/chat | 2026-06-04 | “Send a request to the chat completions endpoint with roles and content as described in the current docs” |
| Responses endpoint request shape | Whether it accepts a messages array or a different input structure | https://apidoc.cometapi.com/api/text/responses | 2026-06-04 | “The Responses endpoint accepts a different input shape — verify the current spec before integrating” |
| Authentication header format | Bearer token vs. API-key header name | https://apidoc.cometapi.com/api/text/chat | 2026-06-04 | “Authenticate using the header format specified in the current CometAPI docs” |
| Response field names | Exact path to the completion text in the response JSON | https://apidoc.cometapi.com/api/text/chat | 2026-06-04 | “Parse the completion text from the field path documented in the current API reference” |
| PR Reviews API shape | Fields required for a pull request review comment | https://docs.github.com/en/pull-requests | 2026-06-04 | “Use the current GitHub pull requests API reference for review comment fields” |
FAQ
Can I use the same CometAPI token for review calls and other agent tasks? That depends on your access control policy. CometAPI docs and the help center are the authoritative source for token scoping options. Verify whether the platform supports scoped tokens or per-project keys before sharing a token across agent workflows.
What happens if the CometAPI endpoint returns a 5xx during a PR review step? Log the HTTP status and the request ID (if the response includes one), then fail the CI step explicitly. Do not silently skip the review or treat a 5xx as a pass. Your retry logic should back off and retry at least once; the exact retry behavior depends on whether the endpoint is idempotent — check the docs.
How do I stop the agent from commenting on every commit instead of just the PR? Scope the review trigger in your CI workflow to pull_request events rather than push events. The GitHub Actions documentation covers event filtering. Your AGENTS.md instruction file can also include a rule that restricts review calls to PR-scoped contexts.
Do I need a different endpoint for structured review output versus conversational review? Yes, potentially. The chat completions endpoint is designed for multi-turn dialogue; the Responses endpoint is designed for structured single-turn outputs. The right choice depends on how you consume the output — a JSON diff annotation versus a freeform comment. Verify both endpoint contracts in the CometAPI docs before deciding.
What if the diff is too large for a single request? Chunk the diff into sections and send one section per request, passing the prior section’s summary as context in the next call. This keeps individual requests within a reasonable context window. Do not assert specific token limits here — verify current context window sizes in the CometAPI models overview.
How do I get started with CometAPI? Visit CometAPI to create an account and access the API documentation.
Reader next step
Turn the next coding-agent request into a one-page task brief, then compare it with How to Write Repository Instructions for Coding Agents . For the surrounding setup and permission baseline, review AI Coding Agent Setup, Security, and Model Routing before assigning broader repository work.
After the repository instruction, secret, and review gates are in place, evaluate CometAPI as the model gateway target for only the writer, reviewer, critic, or fallback roles the team actually needs.