Experimental

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 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

POST

experimental

targets

resolve

curl --request POST \
  --url https://api.githits.dev/v1/experimental/targets/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "limit": 8,
  "name": "Phoenix",
  "preferred_kind": "package",
  "query": "web framework",
  "registries": [
    "hex"
  ]
}
'

{
  "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"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Client-Version

string

Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Agent

string

Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.

X-GitHits-Session-ID

string

Optional session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created.

Query Parameters

fields

string

default:details,availability

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.

Maximum string length: 2048

Body

application/json

A name to resolve, with optional ranking preferences.

name

string

required

Nonblank target name or canonical target string, at most 800 raw UTF-8 bytes.

Minimum string length: 1

intent_hints

string[]

Nonempty list of nonblank hints to help rank relevant targets.

Minimum array length: 1

limit

integer<int32>

default:8

Maximum ranked candidate count; protected and related additions may exceed it.

Required range: 1 <= x <= 20

preferred_kind

enum<string>

Preferred target kind. Influences ranking without excluding other kinds.

Available options:

package,

repository,

site

query

string

Task or question to help rank relevant targets.

registries

enum<string>[]

Optional nonempty ordered list of exact lowercase public registries.

Minimum array length: 1

Available options:

npm,

pypi,

hex,

crates,

vcpkg,

zig,

nuget,

maven,

packagist,

rubygems,

go,

swift

Response

Ranked direct and related canonical targets

Ranked targets with identity, ambiguity, and malicious-package evidence.

ambiguous

boolean

required

Whether the source considers the result ambiguous.

ambiguous_reason

enum<string>

required

Source-owned ambiguity reason; not_ambiguous accompanies false.

Available options:

not_ambiguous,

duplicate_exact_name,

close_candidates,

low_confidence

best

string | null

required

Canonical best target, null when no candidate is best.

protected_matches

string[]

required

Canonical protected exact-name matches in source order.

Whether bounded relation expansion omitted additional targets; direct entries are complete.

targets

object[]

required

Source-ordered direct and bounded relation-expanded targets.

Show child attributes

⌘I

curl --request POST \
  --url https://api.githits.dev/v1/experimental/targets/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "limit": 8,
  "name": "Phoenix",
  "preferred_kind": "package",
  "query": "web framework",
  "registries": [
    "hex"
  ]
}
'

{
  "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"
    }
  ]
}

Get started

v1 reference

Resolve a target name

Selector catalogue

Authorizations

Headers

Query Parameters

Body

Response