Skip to content
GitmoapAPIBeta
Knowledgesearch
GET/repositories/{repo_id}/search

Search one repository

search_repo
  • search:read
    A token needs the search:read scope: Search issues, merge requests, repositories, groups, releases and commentsGranted by mcp_agent, mcp_agent_write, read_api, write_api.Every operation this scope unlocks
  • Filtered across resources

    x-gitmoap-isolation: {"kind":"cross_resource_filtered"}

  • Paginated
    Pass the next_token a page returns to get the next one.

Searches what belongs to the repository, such as its work items, merge requests, releases and comments, most relevant first. Narrow it to some kinds with types; an unknown kind is refused with 400, as is an empty query or one longer than 256 characters. Paginated with limit (20 by default, at most 50) and next_token. Answers 404 for a repository you cannot see. A service account finds only public and internal content.

Parameters

Path
  • repo_idRepositoryId (string · uuid)Repository ID
Query
  • qstringFree text
  • typesstringoptionalComma-separated kinds to search
  • limitinteger · int32optionalPage size (default 20, max 50)
  • next_tokenstringoptionalPagination cursor

Responses

200Ranked hits from the repositoryapplication/json
  • itemsarray of object
    • idstringThe resource's own identifier, as its domain names it (an issue uid, a repository id, a group id, a release tag_name).
    • kindSearchHitKindissuemerge_requestrepositorygroupreleasecommentservicespecwikiWhat kind of thing a search result is.
    • ranknumber · floatHow well the result matches the query; results are ordered by it, highest first.
    • titlestring
    • updated_atstring
    • excerptstring or nulloptionalA short excerpt of the matching body, when the kind has one.
    • iidinteger · int64 or nulloptional0–∞The per-scope sequential number, for the kinds that have one. A comment carries the number of the work item or merge request it was written on.
    • onSearchHitKindissuemerge_requestrepositorygroupreleasecommentservicespecwikior nulloptionalFor a comment: what it was written on, issue or merge_request. With scope and iid it addresses the thread the comment belongs to.
    • pathstring or nulloptionalFor a spec: the document's file in its repository. For a wiki page: the page's path, which is what reads it.
    • scopeScopeRef or nulloptionalThe group or repository the result belongs to — a service's group, a comment's work item's or merge request's scope. Absent for a group and a repository, which are one themselves.
  • next_tokenstring or nulloptional
200 exampleSynthesized example
{
"items": [
{
"id": "id-66ae",
"kind": "issue",
"rank": 69,
"title": "Draw the region map from operation density",
"updated_at": "2026-10-15T03:47:54Z"
},
{
"id": "id-1f23",
"kind": "issue",
"rank": 27,
"title": "Inline scalar newtypes but keep their brand",
"updated_at": "2026-10-10T06:05:59Z"
}
],
"next_token": "next-token-2738"
}
400Missing or invalid q/types/limit/cursorapplication/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
{
"error": {
"code": "code-0f51",
"message": "Inline scalar newtypes but keep their brand"
}
}
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
{
"error": {
"code": "code-1e94",
"message": "Label every synthesized 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
{
"error": {
"code": "code-fc4d",
"message": "Label every synthesized example"
}
}
404Repository not found, or private with no accessapplication/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
{
"error": {
"code": "code-221b",
"message": "Draw the region map from operation density"
}
}

CLI

gitmoap search search-repo

  • --repo-ididRepository ID (id or owner/repo path)
  • --limitnumberoptionalPage size (default 20, max 50)
  • --next-tokenstringoptionalPagination cursor
  • --qstringFree text
  • --typesstringoptionalComma-separated kinds to search

Used in these guides