--- title: "Search GitHub repositories using natural language" method: POST path: "/search/repos/natural-language" --- # Search GitHub repositories using natural language `POST /search/repos/natural-language` Natural language search that uses AI to understand your query and automatically generate search terms and filters. Requires SEARCH service. Credits: 1 per result returned + 1 for AI processing + graph relationship credits if includeAttributes is specified. ## Request body - NaturalLanguageSearchRepositoriesRequest - `query` string, required — Natural language query describing the repositories you want to find - `maxResults` integer — Maximum number of results to return (default: 100, max: 1000) - `first` integer — Alias for maxResults (takes precedence if both provided) - `rankBy` union — Custom ranking formula (AST expression). If not provided, uses default log-normalized 70/20/10 formula (70% semantic similarity, 20% popularity, 10% activity). - object - `type` 'Attr', required - `name` string, required - object - `type` 'Const', required - `value` number, required - object - `type` 'BM25', required - `field` string, required - `query` string, required - object - `type` 'Sum', required - `exprs` union[], required - union - object - `type` 'Attr', required - `name` string, required - object - `type` 'Const', required - `value` number, required - object - `type` 'BM25', required - `field` string, required - `query` string, required - object - `type` 'Sum', required - `exprs` union[], required - … - object - `type` 'Mult', required - `exprs` unknown[], required - … - object - `type` 'Div', required - `exprs` unknown[], required - … - object - `type` 'Max', required - `exprs` union[], required - … - object - `type` 'Min', required - `exprs` union[], required - … - object - `type` 'Log', required - `base` number, required - `expr` union, required - … - object - `type` 'Saturate', required - `expr` union, required - … - `midpoint` number, required - `exponent` number - object - `type` 'Mult', required - `exprs` unknown[], required - unknown - object - `type` 'Div', required - `exprs` unknown[], required - unknown - object - `type` 'Max', required - `exprs` union[], required - union - object - `type` 'Attr', required - `name` string, required - object - `type` 'Const', required - `value` number, required - object - `type` 'BM25', required - `field` string, required - `query` string, required - object - `type` 'Sum', required - `exprs` union[], required - … - object - `type` 'Mult', required - `exprs` unknown[], required - … - object - `type` 'Div', required - `exprs` unknown[], required - … - object - `type` 'Max', required - `exprs` union[], required - … - object - `type` 'Min', required - `exprs` union[], required - … - object - `type` 'Log', required - `base` number, required - `expr` union, required - … - object - `type` 'Saturate', required - `expr` union, required - … - `midpoint` number, required - `exponent` number - object - `type` 'Min', required - `exprs` union[], required - union - object - `type` 'Attr', required - `name` string, required - object - `type` 'Const', required - `value` number, required - object - `type` 'BM25', required - `field` string, required - `query` string, required - object - `type` 'Sum', required - `exprs` union[], required - … - object - `type` 'Mult', required - `exprs` unknown[], required - … - object - `type` 'Div', required - `exprs` unknown[], required - … - object - `type` 'Max', required - `exprs` union[], required - … - object - `type` 'Min', required - `exprs` union[], required - … - object - `type` 'Log', required - `base` number, required - `expr` union, required - … - object - `type` 'Saturate', required - `expr` union, required - … - `midpoint` number, required - `exponent` number - object - `type` 'Log', required - `base` number, required - `expr` union, required - object - `type` 'Attr', required - `name` string, required - object - `type` 'Const', required - `value` number, required - object - `type` 'BM25', required - `field` string, required - `query` string, required - object - `type` 'Sum', required - `exprs` union[], required - union - … - object - `type` 'Mult', required - `exprs` unknown[], required - unknown - object - `type` 'Div', required - `exprs` unknown[], required - unknown - object - `type` 'Max', required - `exprs` union[], required - union - … - object - `type` 'Min', required - `exprs` union[], required - union - … - object - `type` 'Log', required - `base` number, required - `expr` union, required - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - `type` 'Saturate', required - `expr` union, required - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - `midpoint` number, required - `exponent` number - object - `type` 'Saturate', required - `expr` union, required - object - `type` 'Attr', required - `name` string, required - object - `type` 'Const', required - `value` number, required - object - `type` 'BM25', required - `field` string, required - `query` string, required - object - `type` 'Sum', required - `exprs` union[], required - union - … - object - `type` 'Mult', required - `exprs` unknown[], required - unknown - object - `type` 'Div', required - `exprs` unknown[], required - unknown - object - `type` 'Max', required - `exprs` union[], required - union - … - object - `type` 'Min', required - `exprs` union[], required - union - … - object - `type` 'Log', required - `base` number, required - `expr` union, required - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - `type` 'Saturate', required - `expr` union, required - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - `midpoint` number, required - `exponent` number - `midpoint` number, required - `exponent` number - `enablePagination` boolean — Enable cursor-based pagination to fetch results across multiple requests - `after` string — Cursor for pagination (from previous response pageInfo.endCursor) - `includeAttributes` object — Optional graph relationships to include (owner, contributors, starrers) - `owner` boolean — Include repository owner information - `contributors` object — Include repository contributors with cursor pagination - `first` integer, required — Number of items to return (max: 100) - `after` string — Cursor for pagination (opaque base64-encoded) - `filters` union — Optional filters for users. Supports fields like login, company, location, resolvedCountry, resolvedState, resolvedCity. Operators: Eq, NotEq, In, NotIn, Lt, Lte, Gt, Gte. - object - `field` string, required — Field name to filter on - `op` 'Eq' | 'NotEq' | 'In' | 'NotIn' | 'Lt' | 'Lte' | 'Gt' | 'Gte' | 'Glob' | 'NotGlob' | 'IGlob' | 'NotIGlob' | 'Regex' | 'Contains' | 'NotContains' | 'ContainsAny' | 'NotContainsAny' | 'AnyLt' | 'AnyLte' | 'AnyGt' | 'AnyGte' | 'ContainsAllTokens', required — Filter operator - `value` union, required — Filter value (type depends on field and operator) - string - number - boolean - string[] - number[] - object - `op` 'And' | 'Or', required — Composite operator - `filters` object[], required — Array of field filters - `field` string, required — Field name to filter on - `op` 'Eq' | 'NotEq' | 'In' | 'NotIn' | 'Lt' | 'Lte' | 'Gt' | 'Gte' | 'Glob' | 'NotGlob' | 'IGlob' | 'NotIGlob' | 'Regex' | 'Contains' | 'NotContains' | 'ContainsAny' | 'NotContainsAny' | 'AnyLt' | 'AnyLte' | 'AnyGt' | 'AnyGte' | 'ContainsAllTokens', required — Filter operator - `value` union, required — Filter value (type depends on field and operator) - … - object - `op` 'And' | 'Or', required — Composite operator - `filters` union[], required — Array of filters - union - … - `starrers` object — Include users who starred the repository with cursor pagination - `first` integer, required — Number of items to return (max: 100) - `after` string — Cursor for pagination (opaque base64-encoded) - `filters` union — Optional filters for users. Supports fields like login, company, location, resolvedCountry, resolvedState, resolvedCity. Operators: Eq, NotEq, In, NotIn, Lt, Lte, Gt, Gte. - object - `field` string, required — Field name to filter on - `op` 'Eq' | 'NotEq' | 'In' | 'NotIn' | 'Lt' | 'Lte' | 'Gt' | 'Gte' | 'Glob' | 'NotGlob' | 'IGlob' | 'NotIGlob' | 'Regex' | 'Contains' | 'NotContains' | 'ContainsAny' | 'NotContainsAny' | 'AnyLt' | 'AnyLte' | 'AnyGt' | 'AnyGte' | 'ContainsAllTokens', required — Filter operator - `value` union, required — Filter value (type depends on field and operator) - string - number - boolean - string[] - number[] - object - `op` 'And' | 'Or', required — Composite operator - `filters` object[], required — Array of field filters - `field` string, required — Field name to filter on - `op` 'Eq' | 'NotEq' | 'In' | 'NotIn' | 'Lt' | 'Lte' | 'Gt' | 'Gte' | 'Glob' | 'NotGlob' | 'IGlob' | 'NotIGlob' | 'Regex' | 'Contains' | 'NotContains' | 'ContainsAny' | 'NotContainsAny' | 'AnyLt' | 'AnyLte' | 'AnyGt' | 'AnyGte' | 'ContainsAllTokens', required — Filter operator - `value` union, required — Filter value (type depends on field and operator) - … - object - `op` 'And' | 'Or', required — Composite operator - `filters` union[], required — Array of filters - union - … - `ownerDevrank` boolean — Include devrank data for the repository owner - `ownerProfessional` boolean — Include LinkedIn professional profile for the repository owner (requires PROFESSIONAL service) - `filterUserIncludeAttributes` boolean — [Deprecated: Use applyFiltersToIncludeAttributes] When true, applies the LLM-generated filter to all user-returning includeAttributes (contributors, starrers). - `applyFiltersToIncludeAttributes` boolean — When true, applies the LLM-generated filter to all user-returning includeAttributes (contributors, starrers). Alias for filterUserIncludeAttributes. - `dataset` 'standard' | 'professional' — Which dataset to search. 'standard' uses the base namespace; 'professional' uses the LinkedIn-enriched namespace with additional owner LinkedIn fields. ## Response `200` Search results retrieved successfully - NaturalLanguageSearchRepositoriesResponse - `repositories` PublicRepositoryWithGraph[], required — Array of repository search results with relevance scores and optional graph relationships - `id` string, required — BountyLab internal ID - `githubId` string, required — GitHub node ID - `ownerLogin` string, required — Repository owner username - `name` string, required — Repository name - `description` string, nullable — Repository description - `stargazerCount` number, required — Number of stars - `language` string, nullable — Primary programming language - `totalIssuesCount` number, required — Total number of issues (open + closed) - `totalIssuesOpen` number, required — Number of open issues - `totalIssuesClosed` number, required — Number of closed issues - `readmePreview` string, nullable — Preview of repository README (first ~500 chars) - `lastContributorLocations` string[], nullable — Locations of last contributors to this repository - `createdAt` string, nullable — ISO 8601 timestamp when repository was created - `updatedAt` string, nullable — ISO 8601 timestamp when repository was last updated - `embeddedAt` string, nullable — ISO 8601 timestamp when embedding was created - `score` number — Relevance score from search (0-1, lower is more relevant for cosine distance) - `owner` object — Repository owner (when includeAttributes.owner = true) - `id` string, required — BountyLab internal ID - `githubId` string, required — GitHub node ID - `login` string, required — GitHub username - `displayName` string, nullable — User display name - `bio` string, nullable — User biography - `company` string, nullable — Company name - `location` string, nullable — User location - `websiteUrl` string, nullable — User website URL - `socialAccounts` object[], nullable — Social media accounts - `provider` string, required - `url` string, required - `emails` string[], nullable — Obfuscated email addresses showing only the last 2 characters of the local part and full domain (e.g., "***oe@gmail.com"). Use /api/users/best-email endpoint for unobfuscated email access with intelligent selection. - `resolvedCountry` string, nullable — Resolved country from location - `resolvedState` string, nullable — Resolved state/region from location - `resolvedCity` string, nullable — Resolved city from location - `createdAt` string, nullable — ISO 8601 timestamp when user account was created - `updatedAt` string, nullable — ISO 8601 timestamp when user was last updated - `embeddedAt` string, nullable — ISO 8601 timestamp when metadata was extracted - `score` number — Relevance score from search (0-1, lower is more relevant for distance metrics) - `contributors` object — Repository contributors (when includeAttributes.contributors is specified) - `edges` PublicUser[], required — Array of user objects - `id` string, required — BountyLab internal ID - `githubId` string, required — GitHub node ID - `login` string, required — GitHub username - `displayName` string, nullable — User display name - `bio` string, nullable — User biography - `company` string, nullable — Company name - `location` string, nullable — User location - `websiteUrl` string, nullable — User website URL - `socialAccounts` object[], nullable — Social media accounts - `provider` string, required - `url` string, required - `emails` string[], nullable — Obfuscated email addresses showing only the last 2 characters of the local part and full domain (e.g., "***oe@gmail.com"). Use /api/users/best-email endpoint for unobfuscated email access with intelligent selection. - `resolvedCountry` string, nullable — Resolved country from location - `resolvedState` string, nullable — Resolved state/region from location - `resolvedCity` string, nullable — Resolved city from location - `createdAt` string, nullable — ISO 8601 timestamp when user account was created - `updatedAt` string, nullable — ISO 8601 timestamp when user was last updated - `embeddedAt` string, nullable — ISO 8601 timestamp when metadata was extracted - `score` number — Relevance score from search (0-1, lower is more relevant for distance metrics) - `pageInfo` PageInfo, required — Pagination information - `hasNextPage` boolean, required — Whether there are more items available - `endCursor` string, nullable, required — Cursor to fetch next page (null if no more items) - `starrers` object — Users who starred this repository (when includeAttributes.starrers is specified) - `edges` PublicUser[], required — Array of user objects - `id` string, required — BountyLab internal ID - `githubId` string, required — GitHub node ID - `login` string, required — GitHub username - `displayName` string, nullable — User display name - `bio` string, nullable — User biography - `company` string, nullable — Company name - `location` string, nullable — User location - `websiteUrl` string, nullable — User website URL - `socialAccounts` object[], nullable — Social media accounts - `provider` string, required - `url` string, required - `emails` string[], nullable — Obfuscated email addresses showing only the last 2 characters of the local part and full domain (e.g., "***oe@gmail.com"). Use /api/users/best-email endpoint for unobfuscated email access with intelligent selection. - `resolvedCountry` string, nullable — Resolved country from location - `resolvedState` string, nullable — Resolved state/region from location - `resolvedCity` string, nullable — Resolved city from location - `createdAt` string, nullable — ISO 8601 timestamp when user account was created - `updatedAt` string, nullable — ISO 8601 timestamp when user was last updated - `embeddedAt` string, nullable — ISO 8601 timestamp when metadata was extracted - `score` number — Relevance score from search (0-1, lower is more relevant for distance metrics) - `pageInfo` PageInfo, required — Pagination information - `hasNextPage` boolean, required — Whether there are more items available - `endCursor` string, nullable, required — Cursor to fetch next page (null if no more items) - `ownerDevrank` object — Devrank data for the repository owner (when includeAttributes.ownerDevrank = true) - `crackedScore` number, required - `tier` string, required - `rawScore` number, required - `trust` number, required - `pc` number, required - `followersIn` number, required - `followingOut` number, required - `community` integer, required - `createdAt` string, required - `updatedAt` string, required - `ownerProfessional` object — LinkedIn professional profile for the repository owner (when includeAttributes.ownerProfessional = true) - `firstName` string, nullable, required — First name - `lastName` string, nullable, required — Last name - `linkedinUrl` string, required — LinkedIn profile URL - `title` string, nullable, required — Current job title - `headline` string, nullable, required — Professional headline - `organization` string, nullable, required — Current organization/company - `currentIndustry` string, nullable, required — Current industry sector - `city` string, nullable, required — City - `state` string, nullable, required — State or province - `country` string, nullable, required — Country - `location` string, nullable, required — Full location string - `seniorityLevel` string, nullable, required — Seniority level (e.g., Senior, Manager) - `seniority` string, nullable, required — Seniority classification - `functionalArea` string, nullable, required — Functional area (e.g., Engineering, Product) - `expertise` string[], nullable, required — Areas of expertise - `certifications` string[], nullable, required — Professional certifications - `awards` string[], nullable, required — Professional awards - `memberships` string[], nullable, required — Professional organization memberships - `departments` string[], nullable, required — Departments worked in - `patents` string[], nullable, required — Patents held - `publications` string[], nullable, required — Publications authored - `priorIndustries` string[], nullable, required — Previous industries worked in - `languages` string[], nullable, required — Languages spoken - `connectionsCount` number, nullable, required — Number of LinkedIn connections - `followerCount` number, nullable, required — Number of LinkedIn followers - `education` ProfessionalEducation[], required — Education history - `campus` string, nullable, required — Name of the educational institution - `major` string, nullable, required — Field of study or degree program - `specialization` string, nullable, required — Area of specialization - `startDate` string, nullable, required — Start date (YYYY-MM-DD format) - `endDate` string, nullable, required — End date (YYYY-MM-DD format) - `experience` ProfessionalExperience[], required — Work experience history - `company` string, nullable, required — Company or organization name - `title` string, nullable, required — Job title or position - `summary` string, nullable, required — Description of role and responsibilities - `location` string, nullable, required — Work location - `industry` string, nullable, required — Industry sector - `startDate` string, nullable, required — Start date (YYYY-MM-DD format) - `endDate` string, nullable, required — End date (YYYY-MM-DD format, null if current) - `isCurrent` boolean, nullable, required — Whether this is the current position - `count` number, required — Number of repositories returned - `searchQuery` string, required — The generated search query used for semantic search - `pageInfo` object — Pagination info (only present if enablePagination: true was set in request) - `hasNextPage` boolean, required — Whether there are more items available - `endCursor` string, nullable, required — Cursor to fetch next page (null if no more items) ## Other responses - `400` — Bad request - invalid query - `401` — Unauthorized - API key missing - `403` — Forbidden - Invalid API key or SEARCH service access denied - `500` — Internal server error - AI processing failure or search service failure --- [API](https://skmtc.net/bountylaboratories/apis/bounty-lab-public-api.md) · [All operations](https://skmtc.net/bountylaboratories/apis/bounty-lab-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bountylaboratories/bounty-lab-public-api/revisions/910f8a49ca9e/schema)