> ## Documentation Index > Fetch the complete documentation index at: https://docs.githits.com/llms.txt > Use this file to discover all available pages before exploring further. # Resolve a target name > Find packages, repositories, and documentation sites from a name. Results include ranked matches and related projects to help you identify the project you mean. Use this experimental endpoint when you know a project name but need its package coordinates or repository or documentation address for another GitHits request. ## Selector catalogue Use the following selectors with the `fields` query parameter to choose which fields the response includes. See [Choose what the response includes](https://docs.githits.com/api/requests-and-responses#choose-what-the-response-includes) for details. | Selector | Data | Default | | --- | --- | --- | | `details` | Target display_name, description, repository_url, repository_owner, repository_name, documentation_url and license. | Yes | | `availability` | Target docs_available, code_available, docs_page_count, code_file_count, stars, downloads_last_month and downloads_total. | Yes | | `ranking` | Direct-match matched_aliases, match_tier, score and name_similarity. | No | ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/experimental/targets/resolve openapi: 3.1.0 info: description: >- Explore package metadata, security advisories, dependencies, documentation and source code with the GitHits API. ## Choose an operation | Task | Operations | | --- | --- | | Inspect a package | Release metadata, vulnerabilities and dependencies | | Review releases or upgrades | Changelog and batch upgrade reviews | | Read documentation | List package documentation, then read a page | | Navigate source code | List files, read a file or search text within a target | | Compare source trees | Compare files, line statistics and patches between package versions or repository refs | | Discover relevant content | Search across packages, repositories and documentation sites; retrieve a search's status and retained results | | Resolve a target name | Find ranked package, repository and documentation-site targets | | Ask a cited question | Generate an answer grounded in a package, repository or documentation site, or continue a conversation | | Generate an example | Generate and save a code example, then submit feedback | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Percent-encode a package name or opaque read target as one path segment, including any embedded slash. For query values, encode a literal plus sign as `%2B`; ordinary form decoding interprets `+` as a space. Each operation documents its accepted parameters and encoding rules. ## Select the data you need Where supported, `fields` is a comma-separated **query parameter**, including on POST requests. Omit it to use the operation's defaults. Supplying it replaces those defaults; required identity and information needed to interpret the result remain present. A **selector** names a supported **group** of response fields. Groups are atomic: their members are selected together. A **wildcard bundle**, such as `vulnerabilities.*`, selects only the groups listed for that bundle. A bare group does not automatically include nested groups. Arbitrary subfields and undeclared wildcards are not supported. Each operation lists its selectors, defaults, dependencies and the data they return. Selection can reduce transferred data without reducing the work needed to produce it; consult its parameter and response field documentation. Small fixed responses do not offer `fields`. ## Interpret responses and errors An omitted optional field can mean unselected or unavailable data, according to the operation's contract. Null has an operation-specific meaning: it can mark unavailable or inapplicable data, or an unselected search result. Empty arrays, zero and false are values, not substitutes for unavailable data. Always retain the result's completeness and freshness information when displaying or processing it. **Requested** identity records caller intent; **resolved** identity records what that intent resolved to; **served** identity identifies the artifact that produced the response. These can differ while indexing or refresh work continues. Use served identity when an exact follow-up read is required, preserving package-relative or repository-relative path scope. Errors normally use `application/problem+json`. Branch on the stable `code`, not the human-readable `detail`. Include `X-Request-ID` when reporting a problem; error `instance` matches that ID. Respect `Retry-After` when present. If request identity cannot be created, the response is an empty HTTP 500 without a request ID. Responses use `Cache-Control: no-store`. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Ask, generated examples and append-only feedback. Optional `X-GitHits-*` request headers attribute client, agent and session usage. The OpenAPI extension `x-githits-cost` is provisional operation metadata, not a price or a measure of computation. ## Contract status This API is pre-production. The external v1 contract is not yet frozen. license: name: Proprietary title: GitHits Public API version: 0.1.0 servers: - description: Production url: https://api.githits.dev security: [] tags: - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Discover existing documentation pages and read their content with exact source locators and availability information. name: Documentation - description: >- Enumerate files, read exact content and grep within a package or repository. Responses retain served identity, indexing state and completeness information. name: Code - description: >- Discover evidence across package, repository and documentation-site targets, then retrieve retained search results and progress. name: Search - description: >- Find supported programming-language names and aliases for example requests. name: Languages - description: >- Generate code examples for programming tasks, with source references and license attribution. name: Examples - description: Rate generated examples or sessions and provide written feedback. name: Feedback - description: >- Preview operations for target resolution, source comparison and cited questions. Routes use /v1/experimental and may later move to permanent v1 locations under a documented migration policy. name: Experimental paths: /v1/experimental/targets/resolve: post: tags: - Experimental summary: Resolve a target name description: > Find packages, repositories, and documentation sites from a name. Results include ranked matches and related projects to help you identify the project you mean. Use this experimental endpoint when you know a project name but need its package coordinates or repository or documentation address for another GitHits request. ## Selector catalogue Use the following selectors with the `fields` query parameter to choose which fields the response includes. See [Choose what the response includes](https://docs.githits.com/api/requests-and-responses#choose-what-the-response-includes) for details. | Selector | Data | Default | | --- | --- | --- | | `details` | Target display_name, description, repository_url, repository_owner, repository_name, documentation_url and license. | Yes | | `availability` | Target docs_available, code_available, docs_page_count, code_file_count, stars, downloads_last_month and downloads_total. | Yes | | `ranking` | Direct-match matched_aliases, match_tier, score and name_similarity. | No | operationId: resolve_target parameters: - description: >- Comma-separated details, availability, ranking. Omission defaults to details,availability; explicit selection replaces defaults. Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated `fields` query parameters return `400 VALIDATION_ERROR`. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported. in: query name: fields required: false schema: default: details,availability maxLength: 2048 type: string - description: >- Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Name required: false schema: type: string - description: >- Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Version required: false schema: type: string - description: >- Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Agent required: false schema: type: string - description: >- Optional session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created. in: header name: X-GitHits-Session-ID required: false schema: type: string requestBody: content: application/json: examples: package: value: limit: 8 name: Phoenix preferred_kind: package query: web framework registries: - hex site: value: intent_hints: - Node.js - API name: Express documentation preferred_kind: site schema: $ref: '#/components/schemas/ResolveRequest' required: true responses: '200': content: application/json: examples: ambiguous: summary: Protected matches and related target value: ambiguous: true ambiguous_reason: duplicate_exact_name best: npm:phoenix protected_matches: - npm:phoenix - pypi:phoenix related_targets_truncated: false targets: - group_key: project:1 kind: package latest_version: 1.0.0 latest_version_malicious_evidence: advisories: - classification_reasons: - invalid_affected_range osv_id: MAL-2026-2 total_count: 1 truncated: false latest_version_malicious_status: unknown match: confidence: exact protected: true package_name: phoenix registry: npm target: npm:phoenix - group_key: null kind: package latest_version: 0.1.0 latest_version_malicious_evidence: null latest_version_malicious_status: clear match: confidence: exact protected: true package_name: phoenix registry: pypi target: pypi:phoenix - group_key: project:1 kind: repository latest_version: null latest_version_malicious_evidence: null latest_version_malicious_status: not_applicable match: null package_name: null registry: null target: github:example/phoenix default: summary: Default details and availability value: ambiguous: false ambiguous_reason: not_ambiguous best: hex:phoenix protected_matches: - hex:phoenix related_targets_truncated: false targets: - code_available: true code_file_count: 340 description: Productive web framework display_name: Phoenix docs_available: true docs_page_count: 120 documentation_url: https://hexdocs.pm/phoenix downloads_last_month: 2100000 downloads_total: 42000000 group_key: hex:phoenix kind: package latest_version: 1.8.1 latest_version_malicious_evidence: null latest_version_malicious_status: clear license: MIT match: confidence: exact protected: true package_name: phoenix registry: hex repository_name: null repository_owner: null repository_url: https://github.com/phoenixframework/phoenix stars: 23000 target: hex:phoenix empty: summary: No source candidates value: ambiguous: false ambiguous_reason: not_ambiguous best: null protected_matches: [] related_targets_truncated: false targets: [] full: summary: All three groups with affected evidence value: ambiguous: false ambiguous_reason: not_ambiguous best: npm:example protected_matches: [] related_targets_truncated: true targets: - code_available: true code_file_count: 12 description: null display_name: example docs_available: false docs_page_count: 0 documentation_url: null downloads_last_month: 0 downloads_total: 0 group_key: null kind: package latest_version: 2.0.0 latest_version_malicious_evidence: advisories: - classification_reasons: - affected_version_range_match osv_id: MAL-2026-1 total_count: 1 truncated: false latest_version_malicious_status: affected license: null match: confidence: high match_tier: 2 matched_aliases: - example.js name_similarity: 0.94 protected: false score: 91 package_name: example registry: npm repository_name: null repository_owner: null repository_url: null stars: 0 target: npm:example sparse: summary: Mandatory context with all groups unselected value: ambiguous: false ambiguous_reason: not_ambiguous best: site:example.org protected_matches: [] related_targets_truncated: false targets: - group_key: null kind: site latest_version: null latest_version_malicious_evidence: null latest_version_malicious_status: not_applicable match: confidence: high protected: false package_name: null registry: null target: site:example.org schema: $ref: '#/components/schemas/ResolveResponse' description: Ranked direct and related canonical targets headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '400': content: application/problem+json: example: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Validation error (VALIDATION_ERROR). headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Authentication required (AUTHENTICATION_REQUIRED). headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- Forbidden (FORBIDDEN, ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED, TERMS_ACCEPTANCE_REQUIRED). headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '405': content: application/problem+json: example: code: METHOD_NOT_ALLOWED detail: The requested method is not supported for this route. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 405 title: Method not allowed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: 'METHOD_NOT_ALLOWED: the route does not support this HTTP method.' headers: Allow: description: 'Supported methods: POST.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Rate limited (RATE_LIMITED). headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '500': description: >- Request identity could not be created. Empty body without X-Request-ID; no problem object is available. headers: Cache-Control: schema: enum: - no-store type: string x-githits-empty-identity-failure: true '502': content: application/problem+json: example: code: UPSTREAM_ERROR detail: The upstream service failed to provide a response. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Upstream error (UPSTREAM_ERROR). headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '504': content: application/problem+json: example: code: TIMEOUT detail: The upstream request did not complete in time. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Upstream timeout (TIMEOUT). headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string security: - bearer_auth: [] components: schemas: ResolveRequest: additionalProperties: false description: A name to resolve, with optional ranking preferences. properties: intent_hints: description: Nonempty list of nonblank hints to help rank relevant targets. items: type: string minItems: 1 type: array limit: default: 8 description: >- Maximum ranked candidate count; protected and related additions may exceed it. format: int32 maximum: 20 minimum: 1 type: integer name: description: >- Nonblank target name or canonical target string, at most 800 raw UTF-8 bytes. minLength: 1 type: string preferred_kind: $ref: '#/components/schemas/ResolveTargetKind' description: >- Preferred target kind. Influences ranking without excluding other kinds. query: description: Task or question to help rank relevant targets. type: string registries: description: Optional nonempty ordered list of exact lowercase public registries. items: enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift type: string minItems: 1 type: array required: - name type: object ResolveResponse: description: Ranked targets with identity, ambiguity, and malicious-package evidence. properties: ambiguous: description: Whether the source considers the result ambiguous. type: boolean ambiguous_reason: $ref: '#/components/schemas/ResolveTargetAmbiguousReason' description: Source-owned ambiguity reason; `not_ambiguous` accompanies false. best: description: Canonical best target, null when no candidate is best. type: - string - 'null' protected_matches: description: Canonical protected exact-name matches in source order. items: type: string type: array related_targets_truncated: description: >- Whether bounded relation expansion omitted additional targets; direct entries are complete. type: boolean targets: description: Source-ordered direct and bounded relation-expanded targets. items: $ref: '#/components/schemas/ResolveTarget' type: array required: - best - protected_matches - targets - ambiguous - ambiguous_reason - related_targets_truncated type: object ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: An optional acceptance URL supplied by the upstream allow-list. type: string code: description: The stable uppercase API error code. type: string detail: description: A stable, client-safe explanation of the failure. type: string instance: description: The active request trace ID. type: string status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: An optional terms URL supplied by the upstream allow-list. type: string title: description: A short, stable title for the error. type: string type: description: The generic RFC 9457 problem type. type: string required: - type - title - status - detail - instance - code type: object ResolveTargetKind: description: A package, repository, or documentation-site target kind. enum: - package - repository - site type: string ResolveTargetAmbiguousReason: description: Source-owned explanation for ambiguity. enum: - not_ambiguous - duplicate_exact_name - close_candidates - low_confidence type: string ResolveTarget: description: >- One direct or related target with mandatory identity and optionally selected evidence. properties: code_available: description: Selected code availability; omitted when unselected. type: boolean code_file_count: description: Selected code file count; null when unavailable. format: int32 type: - integer - 'null' description: description: >- Selected description; omitted when unselected and null when unavailable. type: - string - 'null' display_name: description: Selected display name; omitted without the details group. type: string docs_available: description: Selected documentation availability; omitted when unselected. type: boolean docs_page_count: description: Selected documentation page count; null when unavailable. format: int32 type: - integer - 'null' documentation_url: description: >- Selected documentation URL; omitted when unselected and null when unavailable. type: - string - 'null' downloads_last_month: description: Selected recent package downloads; null when unavailable. format: int32 type: - integer - 'null' downloads_total: description: Selected total package downloads; null when unavailable. format: int32 type: - integer - 'null' group_key: description: Opaque response-local relation grouping hint; null is a singleton. type: - string - 'null' kind: $ref: '#/components/schemas/ResolveTargetKind' description: Package, repository, or standalone documentation site. latest_version: description: Displayed latest package version when available; null otherwise. type: - string - 'null' latest_version_malicious_evidence: oneOf: - type: 'null' - $ref: '#/components/schemas/ResolveMaliciousEvidence' description: >- Bounded active malicious evidence for affected/unknown; null for clear/not-applicable. latest_version_malicious_status: $ref: '#/components/schemas/ResolveTargetLatestVersionMaliciousStatus' description: >- Source decision for malicious content affecting the displayed latest version. license: description: >- Selected declared license; omitted when unselected and null when unavailable. type: - string - 'null' match: oneOf: - type: 'null' - $ref: '#/components/schemas/ResolveMatch' description: Direct ranking evidence; null exactly for a related addition. package_name: description: Canonical package name for a package; null otherwise. type: - string - 'null' registry: description: >- Canonical registry for a package; null for repository and site targets. enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift - null type: - string - 'null' repository_name: description: >- Selected repository name; omitted when unselected and null when unavailable. type: - string - 'null' repository_owner: description: >- Selected repository owner; omitted when unselected and null when unavailable. type: - string - 'null' repository_url: description: >- Selected repository URL; omitted when unselected and null when unavailable. type: - string - 'null' stars: description: Selected public GitHub stars; null when unavailable. format: int32 type: - integer - 'null' target: description: Canonical target accepted by downstream `GitHits` operations. type: string required: - target - kind - registry - package_name - latest_version - group_key - match - latest_version_malicious_status - latest_version_malicious_evidence type: object ResolveMaliciousEvidence: description: Bounded evidence behind an affected or unknown malicious decision. properties: advisories: description: >- At most five active malicious advisories, ordered by OSV ID upstream. items: $ref: '#/components/schemas/ResolveMaliciousAdvisory' type: array total_count: description: Total relevant advisory count before the evidence bound. format: int32 type: integer truncated: description: Whether the evidence array omitted relevant advisories. type: boolean required: - advisories - total_count - truncated type: object ResolveTargetLatestVersionMaliciousStatus: description: Source-owned latest-version malicious-content decision. enum: - not_applicable - clear - affected - unknown type: string ResolveMatch: description: >- Mandatory direct-match confidence and protection with optional ranking diagnostics. properties: confidence: $ref: '#/components/schemas/ResolveTargetConfidence' description: Source-owned confidence bucket. match_tier: description: Selected source ranking tier. format: int32 type: integer matched_aliases: description: Selected matched aliases, preserving source order. items: type: string type: array name_similarity: description: Selected lexical signal; null when no fuzzy evidence was retrieved. format: double type: - number - 'null' protected: description: >- Whether source curation protects this exact-name match from candidate limiting. type: boolean score: description: >- Selected opaque source score; not a probability or cross-request metric. format: double type: number required: - confidence - protected type: object ResolveMaliciousAdvisory: description: One active OSV malicious advisory and complete classification reasons. properties: classification_reasons: description: >- Complete source-owned reasons for affected or unknown classification. items: $ref: >- #/components/schemas/ResolveTargetMaliciousAdvisoryClassificationReason type: array osv_id: description: Stable active OSV advisory identifier. type: string required: - osv_id - classification_reasons type: object ResolveTargetConfidence: description: Source-owned confidence bucket for one direct match. enum: - exact - high - medium - low type: string ResolveTargetMaliciousAdvisoryClassificationReason: description: >- Why one malicious advisory affected or could not classify the displayed version. enum: - affected_version_range_match - missing_displayed_version - invalid_displayed_version - missing_affected_ranges - empty_affected_ranges - invalid_affected_range type: string securitySchemes: bearer_auth: scheme: bearer type: http ````