Manage Learnings with the API

Learnings are the review preferences CodeRabbit saves from your team’s feedback. The API has two sets of operations for them. Both work on your organization’s Learnings; they differ in what they can do and which keys they accept.

Before you start

• See Authentication for the keys each operation family accepts and Conventions for base URLs, pagination, errors, and rate limits.
• The curl examples read the key from CODERABBIT_API_KEY. The CLI examples use the coderabbit api command with a key file.

Choose an operation set

Use the organization Learnings operations to:

• Export Learnings to CSV.
• Read the Learnings of every organization in an SSO workspace at once with a workspace API token.
• Work with GitLab, Bitbucket, Azure DevOps, or self-hosted CodeRabbit.

Use the Knowledge Base Learnings operations to:

• Create Learnings.
• Read usage statistics or the values you can filter by.
• Work through the MCP server.

List and export organization Learnings

1. Call List learnings for an organization. Its reference lists the filters: text search, file paths, repositories, authors, and recent use.
   curl

   CLI

   curl --get "https://api.coderabbit.ai/v1/learnings" \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --data-urlencode "stat_filter=never_used" \
     --data-urlencode "limit=500"
   
2. While next_cursor isn’t null, request the next page with cursor set to that value and the same filters. Results come newest first, up to 1,000 per page.
3. To download a file instead, add format=csv. The CSV columns match the JSON fields. A CSV response holds a single page of up to limit rows and has no cursor, so use JSON when you expect more rows than limit. The CLI prints JSON only; download CSV with curl.

A response larger than 16 MiB returns 413; add filters or lower limit. With a workspace token, org_id selects one organization; without it, the response covers every organization in the workspace.

Update or delete organization Learnings

1. Take the Learning’s id from the list.
2. Call Update a learning (PATCH /v1/learnings/{learning_id}) with the new text in learning. With a workspace token, also send org_id. CodeRabbit trims the text and redacts recognized credentials before saving it. A 204 response means the update is saved. The CLI example reads the same body from learning.json.
   curl

   CLI

   curl "https://api.coderabbit.ai/v1/learnings/$LEARNING_ID" \
     --request PATCH \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"learning": "Prefer early returns over nested conditionals in request handlers."}'
   
3. To remove a Learning, call Delete a learning (DELETE /v1/learnings/{learning_id}), with org_id in the query for a workspace token. Deletion is idempotent: it returns 204 even when the Learning is already gone, so a retry is safe.

The key owner needs the learning:write permission, which the Read and Write level of the Learnings permission grants. If an update returns 500, send the same request again.

Create Learnings in the Knowledge Base

1. Call Save Learnings with a learnings array. Each item needs repoOwner, repoName, learning, and user. Add file, startLine, endLine, pullRequest, or url to tie the Learning to code. The CLI example reads the same body from learnings.json.
   curl

   CLI

   curl "https://api.coderabbit.ai/v1/knowledge/learnings" \
     --request POST \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{
       "learnings": [
         {
           "repoOwner": "acme",
           "repoName": "backend",
           "learning": "Use the shared retry helper for outbound HTTP calls.",
           "user": "jane",
           "file": "src/http/client.ts"
         }
       ]
     }'
   
2. Read learning_ids in the response. Saving can create new Learnings or update matching ones, so an ID can belong to a Learning you saved before. If learning_ids is null, don’t send the request again to find the IDs; list the Learnings instead.
3. Read a Learning with Read a saved Learning, change its text with Update a Learning (PATCH /v1/knowledge/learnings/{learning_id}), or remove it with Delete a Learning (DELETE /v1/knowledge/learnings/{learning_id}).

Find and analyze Knowledge Base Learnings

• List saved Learnings returns numbered pages of up to 100 Learnings, sorted and filtered the way the Learnings page in the app does.
• Read available Learning filters returns the repository names, files, and users you can filter by.
• Read recorded Learning usage statistics returns four counts for the filters you pass: all Learnings, active Learnings, Learnings never used, and Learnings created this week.
• Export saved Learnings returns every matching Learning in one JSON response, without paging.

usage_count and last_used reflect the usage CodeRabbit recorded. Treat them as best effort, not as proof that a Learning was or wasn’t applied. The key owner’s Learnings permissions apply to every operation. For errors and paging details, see Errors and Pagination.

What’s next