> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Learnings with the API

> Choose between the organization Learnings operations and the Knowledge Base Learnings operations, then list, export, create, update, and delete Learnings with the CodeRabbit API.

[Learnings](https://docs.coderabbit.ai/knowledge-base/learnings.md) 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](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts) for the keys each operation family accepts and [Conventions](https://docs.coderabbit.ai/api/conventions.md) 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](https://docs.coderabbit.ai/api/cli) with a key file.

## Choose an operation set

| | Organization Learnings | Knowledge Base Learnings |
| - | - | - |
| Path | `/v1/learnings` | `/v1/knowledge/learnings` |
| Operations | List (JSON or CSV), update, delete | List, read, create, update, delete, statistics, filter values, full download |
| Formats | JSON pages or a CSV file | JSON |
| Organizations | Enterprise organizations on every Git provider, including self-hosted CodeRabbit | GitHub Cloud organizations |
| Operation family | [Export and user-management operations](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts) | [Product operations](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts) |
| Hosted MCP | Not available | Each operation is an MCP tool with the same name |

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](https://docs.coderabbit.ai/api/mcp.md).

## List and export organization Learnings

1. Call [List learnings for an organization](https://docs.coderabbit.ai/api/reference/learnings-list.md). Its reference lists the filters: text search, file paths, repositories, authors, and recent use.

   ```bash curl theme={null}
   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"
   ```

   ```bash CLI theme={null}
   coderabbit api --api-key-file ~/.config/coderabbit/api-key request '/learnings?stat_filter=never_used&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.

> [!WARNING]
>
> Filter by repository with `repository_ids` only. The operation ignores query parameters it doesn't know, so a misspelled filter, or `repository_id` in the singular, returns a broader set of Learnings instead of an error.

## Update or delete organization Learnings

1. Take the Learning's `id` from the list.

2. Call [Update a learning](https://docs.coderabbit.ai/api/reference/learnings-update.md) (`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`.

   ```bash curl theme={null}
   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."}'
   ```

   ```bash CLI theme={null}
   coderabbit api --api-key-file ~/.config/coderabbit/api-key request -X PATCH "/learnings/$LEARNING_ID" --input learning.json
   ```

3. To remove a Learning, call [Delete a learning](https://docs.coderabbit.ai/api/reference/learnings-delete.md) (`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](https://docs.coderabbit.ai/api/reference/create-learnings.md) 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`.

   ```bash curl theme={null}
   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"
         }
       ]
     }'
   ```

   ```bash CLI theme={null}
   coderabbit api --api-key-file ~/.config/coderabbit/api-key request /knowledge/learnings --input learnings.json
   ```

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](#find-and-analyze-knowledge-base-learnings) instead.

3. Read a Learning with [Read a saved Learning](https://docs.coderabbit.ai/api/reference/get-learning.md), change its text with [Update a Learning](https://docs.coderabbit.ai/api/reference/update-learning.md) (`PATCH /v1/knowledge/learnings/{learning_id}`), or remove it with [Delete a Learning](https://docs.coderabbit.ai/api/reference/delete-learning.md) (`DELETE /v1/knowledge/learnings/{learning_id}`).

## Find and analyze Knowledge Base Learnings

* [List saved Learnings](https://docs.coderabbit.ai/api/reference/list-learnings.md) returns numbered pages of up to 100 Learnings, sorted and filtered the way the **Learnings** page in the app does.
* [Read available Learning filters](https://docs.coderabbit.ai/api/reference/get-learning-filters.md) returns the repository names, files, and users you can filter by.
* [Read recorded Learning usage statistics](https://docs.coderabbit.ai/api/reference/get-learning-statistics.md) returns four counts for the filters you pass: all Learnings, active Learnings, Learnings never used, and Learnings created this week.
* [Export saved Learnings](https://docs.coderabbit.ai/api/reference/export-learnings.md) 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](https://docs.coderabbit.ai/api/conventions.md#errors) and [Pagination](https://docs.coderabbit.ai/api/conventions.md#pagination).

## What's next

> [card] [Learnings](https://docs.coderabbit.ai/knowledge-base/learnings.md)
>
> Learn how CodeRabbit records Learnings, applies them in reviews, and scopes them to repositories.

> [card] [Connect an MCP client](https://docs.coderabbit.ai/api/mcp.md)
>
> Connect an MCP client to manage Learnings with the same operations as tools.

> [card] [Review instructions](https://docs.coderabbit.ai/configuration/path-instructions.md)
>
> Write lasting path-based review rules when a Learning isn't the right fit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.