Skip to main content
Use this recipe to drive Coding Agent from a script or an agent: create a task, follow it, review its plan, and deliver its patch. The task page in the app shows the same task, so people can follow and steer it there too.

Before you start

  • You need a user or agentic API key for a GitHub Cloud organization that can use Coding Agent; if the same job also requests CodeRabbit reviews, use an agentic key for the whole flow. See Authentication for keys and Conventions for base URLs, pagination, errors, and rate limits.
  • Tasks act as the key’s owner: that person’s repository access, Coding Agent permissions, and billing apply. See Access and billing.
  • The curl examples read the key from CODERABBIT_API_KEY and the API host from CODERABBIT_API_HOST; Set up your shell sets both. The CLI has no dedicated commands for these operations; the CLI examples call them through coderabbit api request. To work with tasks interactively in a terminal, use cr code instead.
  • On the hosted MCP server, every operation on this page is a tool with the same name as its operation ID, such as create_code_task. Reads need the code:read scope and changes need code:write.

1. Create a task

Create a task with a JSON body. Save it as task.json:
Set mode to plan to get a plan to review first; without it, the agent changes code directly. See Code mode and Plan mode. client_request_id is required: give each new task its own, and a retry with the same ID returns the task already created, as Retry safely explains. Create a task lists every field and its limits.
The response holds the task and created, which is false when the client_request_id matched a task you already created. Save task.task_id; the examples below read it from TASK_ID. Creating a task never pushes code: the work ends as a proposed patch that you deliver in step 6.

2. Follow the task

Poll Get a task to see where the task is.
status tells you what the task needs next. These values need your attention: While work is in progress, status is queued, running, revising, applying, or resolving_conflicts. A polling loop stops at plan_ready, patch_ready, and conflicts_detected, which wait for you, and at the final states completed, no_file_changes, failed, canceled, rejected, and stale. A question from the agent doesn’t change the task’s status: while it is running, also read the latest turn, and when its waiting_for_interaction_id is set, answer the question before you poll again. Poll every 10 seconds or less often; Get a task has its own budget under rate limits. plan_version is null until the task has a plan. Follow the work explains the states as the app shows them. Each instruction the agent works on is a turn. List turns returns the newest 20 turns, oldest first. For older turns, pass next_before_turn_start_seq as before_turn_start_seq. To read what the agent said at the end of a turn, call Get a turn with its start_seq:
A turn’s status is running, patch_ready, completed, canceled, or failed. For a completed or patch_ready turn, result.text holds the agent’s final reply. result is null while the turn runs or when no final reply was kept. A failed turn has a general error.message; open the task in the app for details. Old turns eventually return 404 not_found.

Answer a question

When the agent needs your input, the turn’s waiting_for_interaction_id is set. List questions and find the entry whose question.interactionId matches it. Each item in question.questions has an id, the question text, and sometimes options to choose from. Answer with Answer a question. client_operation_id must be a UUID, and answers maps each question id to your answers:
The response’s result is accepted, duplicate, deferred, or rejected, with a reason when it has one. Prompts that ask for permission to use the owner’s personal connections, or ask how to deliver the work, return 412 precondition_failed; answer those on the task page in the app.

Send a follow-up or stop a turn

  • To give the agent another instruction, send a follow-up with message and a client_operation_id. CodeRabbit queues it and runs it as a new turn; Get the queue shows messages still waiting.
  • To stop the running turn, stop the task, optionally with a reason. It works like Stop on the task page, including what happens to queued messages; see Stop a task. It doesn’t stop CodeRabbit reviews.
Both calls return 202 when CodeRabbit accepts them. Keep polling the task for the result.

3. Read the plan

In plan mode, the task stops at plan_ready with a plan_version. Get the plan for that version:
PLAN_VERSION is the task’s plan_version. The response has the plan’s markdown, its approvals, and the version and sha256 that identify this exact plan. Every revision creates a new version. Feedback and approval calls take both version and sha256, and return 409 conflict when they don’t match the current plan; read the task and the plan again, then decide how to continue. The examples below read the hash from PLAN_SHA256:

4. Work with plan feedback

People start feedback threads by selecting plan text on the task page; the API can’t start a thread, but it can reply to, resolve, and reopen the threads that exist. A script that wants to send feedback shouldn’t wait for a thread: revise the plan with a message, which needs no thread. List plan feedback returns the open and resolved threads for one plan version, without deleted comments:
Each thread has an id, a status of open or resolved, a location.quote with the plan text it’s about, and its comments, each with its own id, text, and author. Thread actions use the thread id; editing and deleting use the comment id: For example, to reply to a thread and then resolve it, build both request bodies from plan.json, which you saved when you read the plan, then send them:
A reply returns 201 with the new comment_id and the updated feedback. Keep these rules in mind:
  • Replying doesn’t reopen a resolved thread, and resolving a thread doesn’t approve the plan or start implementation.
  • The API doesn’t limit resolving to a thread’s author, so a key can resolve threads that other people started. That closes their feedback without their agreement, so a script should resolve only threads it replied to and use Revise for the rest.
  • Only a comment’s author can replace or delete it. A replacement keeps the mentions whose tokens are still in the new text.
  • Replies have no retry key. If a reply times out, list the feedback before you send it again, so you don’t post it twice.
Deleting the first comment of a thread deletes the whole thread, including other people’s replies. Deleting a reply removes only that reply.

5. Approve, revise, or implement the plan

These calls finish the plan review. They’re separate calls: approving a plan doesn’t start implementation, and implementing doesn’t require an approval.
  • Approve. Set the plan approval (PUT) with version, sha256, and approved: true. Send approved: false to withdraw your approval. The plan’s author is the person who created the task: they can’t approve their own plan and get 403 forbidden, so send the approval with another person’s key. See Review a plan.
  • Revise. Request a revision with your feedback as message and a client_operation_id. When the revision finishes, the task’s plan_version increases; read the new plan from step 3.
  • Implement. Implement the plan with the version and a client_operation_id. While any feedback thread on that version is open, including a thread a person started, the call returns 409 conflict; resolve the threads or revise the plan first. CodeRabbit implements each plan version once, so repeating the call for the same version doesn’t queue the work twice.
Build the bodies from plan.json:
To approve the plan:
The response is the plan with its updated approvals. To implement it:
Revision and implementation return 202 when CodeRabbit accepts them. Follow the task from step 2 until it reaches plan_ready again or patch_ready.

6. Deliver the patch

When the task reaches patch_ready, read the proposed patch with Get the patch. patch.patch holds the unified diff. patch is null when the task has no patch, and preview_status is too_large when the diff is too large to return; review it on the task page instead. Then deliver the patch. delivery_mode chooses how it lands: Without delivery_mode, CodeRabbit commits to the task’s pull request when it has one, and opens a new pull request otherwise. A new pull request opens against the task’s working branch, as Deliver a task’s changes explains, and the API has no field for its title or body. That page also covers both modes and who the commits are attributed to.
A 202 response means CodeRabbit accepted the delivery. Poll the task until pull_request_url is set or status reports a problem. Delivery pushes with the key owner’s own GitHub authorization, which they connect in the CodeRabbit app. If it’s missing or expired, delivery returns 401 unauthenticated even though the API key is valid; reconnect GitHub in the app and deliver again. Branch protections still apply; see When delivery is blocked. Delivery has no retry key. If a request times out, read the task and the pull request before you send it again.

7. Turn on Autofix

Autofix publishes a task’s work and keeps fixing review findings, failing checks, and merge conflicts on its pull request. Get Autofix status takes a target, either a task or a pull request:
For a pull request, use target[type]=pull_request with target[repoId] and target[prNumber]. The response says whether Autofix is available for the target. watch is null when Autofix isn’t set up for the target; otherwise it reports enabled, state, prUrl, and a reason when there is one. To change it, send an Autofix command with the same target and an action: enable, disable, resume, or recover. recover also takes the deliveryConflict object from the status response.
Enabling Autofix authorizes CodeRabbit to publish changes and follow-up fixes without approving each patch. Repository permissions and branch protections still apply.

8. Request a review of the delivered pull request

When delivery sets pull_request_url (for example https://github.com/acme/api/pull/42), the pull request number is its last path segment, and the repository ID is the task’s repository_id. Read both from Get a task:
Read the review status of that pull request first, and request a review only when the current head has none running or completed. A review request needs an agentic key; see Authentication.
The pull request reviews guide covers the request, the status values, and what to do when review is null.

Run it unattended

One agentic key can run every step of this flow. Approving a plan is the exception for tasks the key’s own owner created, and a few steps need a person or the app: Give the bot its own account as the key owner. An agentic key’s owner needs a seat, and delivery uses that account’s GitHub authorization, so the pull requests and commits are attributed to it; see Who pushes, and who wrote it. Leave is_private unset on tasks that another account must approve, because a private task is visible only to its author.
  • Feedback threads on a plan start in the app. The API can reply to, resolve, and reopen threads, but can’t start one. To send feedback from a script, revise the plan with a message. List the feedback before you act on it.
  • Approval needs a second account. The plan’s author is the account that created the task, so a bot can’t approve the plans of tasks it created; a key owned by another account, such as a second bot, can. Implementation doesn’t check for an approval; if your process requires one, read the plan’s approvals before you implement.
  • Delivery needs the key owner’s GitHub authorization. The key’s owner connects GitHub in the CodeRabbit app, and CodeRabbit renews that authorization on its own. The API can’t connect it: when it’s missing or GitHub no longer accepts it, delivery returns 401 unauthenticated until the owner reconnects GitHub in the app, so alert a person instead of retrying.
  • Some questions need the app. Questions about the owner’s personal connections or how to deliver the work return 412 precondition_failed; a person answers them on the task page. See Answer a question.
  • No webhooks. The API doesn’t notify you when a task changes. Poll Get a task, and stay within your rate limit.
  • No lookup by client_request_id. Tasks don’t return it, and List tasks can’t filter by it. To find a task after a crash, send the same create request again.
  • No GitHub issue link, and no pull request title or body. A task has no field for a GitHub issue, and delivery takes only delivery_mode, so the pull request can’t say Fixes #123. Put everything the agent needs from the issue in instructions, and edit the pull request on GitHub afterward.

Retry safely

Some calls take a key that makes a retry safe; others need a read first. CodeRabbit remembers a client_request_id for as long as the task exists, archived or not, and matches it per key owner and repository. It doesn’t compare the rest of the body, so the same ID with new instructions returns the first task. Use a new ID for each new task, for example by adding an attempt number.

Handle errors

All errors use the error format described in Errors. Error messages are generic, so use the status and the step you were on to find the cause:

What’s next

Request and read reviews

Request a CodeRabbit review of the pull request your task opened and read the results.

Work with a running task

See how the same task looks on its task page, where people can steer it and review its plan.

Connect an MCP client

Connect an AI agent to CodeRabbit and call these operations as MCP tools.