GET/repositories/{repo_id}/merge-requests/cards

List merge requests as rich cards for the UI list view

list_mr_cards

merge_request:read
A token needs the merge_request:read scope: View merge requestsGranted by mcp_agent, mcp_agent_write, read_api, read_repository, write_api, write_repository.Every operation this scope unlocks
Single-resource
x-gitmoap-isolation: {"kind":"single_or_self_scoped"}
Paginated
Pass the next_token a page returns to get the next one.

The card form of the repository listing: each merge request with its author, reviewers, approvals, commit and comment counts, open threads, diff size and whether it is stacked, most recently updated first. A signed-in caller also gets a badge saying whether each one can merge and whether it conflicts. Pages hold up to 25 cards, 10 by default.

Parameters

Path

repo_idRepositoryId (string · uuid)Repository ID

Query

statusstringoptionalFilter by status: open, merged, closed
draftstringoptionalFilter by draft flag: true or false
searchstringoptionalSearch the title and description by word or phrase, or the title by any part of it
limitinteger · int32optionalPage size (1-25, default 10)
next_tokenstringoptionalPagination cursor

Responses

200Merge request cards listedapplication/json

itemsarray of MergeRequestCard
- The MergeRequestCard schema
- approvalsApprovalSummary
  - The ApprovalSummary schema
  - giveninteger · int320–∞
  - requiredinteger · int320–∞
- authorActorSummary
  - The ActorSummary schema
  - emailstring
  - idstring
  - usernamestring
  - avatar_urlstring or nulloptional
- comments_countinteger · int320–∞
- commits_countinteger · int320–∞
- created_atstring
- diffDiffSummary
  - The DiffSummary schema
  - additionsinteger · int320–∞
  - deletionsinteger · int320–∞
- is_draftboolean
- merge_request_idMergeRequestId (integer · int64)
- repository_idRepositoryId (string · uuid)
- reviewersarray of CardReviewer
  - The CardReviewer schema
  - emailstring
  - idstring
  - review_statusReviewStatuspendingapprovedrejected
  - stalebooleanWhether this reviewer's approval predates the current source-branch tip (approved an older revision). Computed at read time; always present.
  - usernamestring
  - avatar_urlstring or nulloptional
- source_branchBranchName (string)
- statusMergeRequestStatusopenmergedclosed
- target_branchBranchName (string)
- threadsThreadSummary
  - The ThreadSummary schema
  - resolvedinteger · int320–∞
  - totalinteger · int320–∞
- titleMrTitle (string)
- updated_atstring
- author_can_pushboolean or nulloptionalWhether the author can push to the repository — false for a drive-by contributor's merge request. Absent where it was not computed.
- is_stackedbooleanoptionalTrue when the merge request is part of a stack: an open merge request is based on it, or it is based on one.
- mergeMergeStatusSummary or nulloptional
  - The MergeStatusSummary schema
  - has_conflictsboolean
  - mergeableboolean
- my_review_statusReviewStatuspendingapprovedrejectedor nulloptionalYour own review status on the merge request. Present only in the listing of merge requests awaiting your review.
- pipeline_stateMrPipelineStatependingrunningfailedpassedemptyor nulloptionalWhere the merge request's pipelines stand at its head: pending, running, failed, passed, or empty when no pipeline applies. Present only in a repository's own listing, whether or not the repository requires the pipelines to pass.
next_tokenstring or nulloptional

200 exampleSynthesized example

400Bad request — a path parameter is not a well-formed value of its typeapplication/json

Error codes

BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

400 exampleSynthesized example

401Unauthenticated — no credential, or an invalid oneapplication/json

Error codes

UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

401 exampleSynthesized example

403Forbidden — the caller's access level or token scope is insufficientapplication/json

Error codes

FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

403 exampleSynthesized example

404Not found — or found and private, which is masked as absentapplication/json

Error codes

NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

404 exampleSynthesized example

CLI

gitmoap mr list-cards

--repo-ididRepository ID (id or owner/repo path)
--draftstringoptionalFilter by draft flag: true or false
--limitnumberoptionalPage size (1-25, default 10)
--next-tokenstringoptionalPagination cursor
--searchstringoptionalSearch the title and description by word or phrase, or the title by any part of it
--statusstringoptionalFilter by status: open, merged, closed

Used in these guides

Merge requests

Request

curl "https://api.gitmoap.com/repositories//merge-requests/cards" \
  -H "Authorization: Bearer $GITMOAP_TOKEN"

gitmoap mr list-cards \
  --repo-id

import { createApiClient } from "@gitmoap/backend-types";

const client = createApiClient({
  baseUrl: "https://api.gitmoap.com",
  headers: { Authorization: `Bearer ${process.env.GITMOAP_TOKEN}` },
});

const { data, error } = await client.GET("/repositories/{repo_id}/merge-requests/cards", {
  params: {
    path: { repo_id: "" },
  },
});

GET /repositories//merge-requests/cards HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN

⌘↵

Send to see the sandbox's answer. Nothing leaves your browser.