List package or repository code files

GET

code

files

GET /v1/code/files?registry=npm&name=%40scope%2Fpackage HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>

{
  "code_index_state": "current",
  "files": [
    {
      "byte_size": 0,
      "file_type": "source",
      "language": "rust",
      "name": "main.rs",
      "path": "src/main.rs"
    }
  ],
  "indexing_ref": null,
  "limit": 200,
  "offset": 0,
  "returned": 1,
  "target_resolution": {
    "freshness": "current",
    "freshness_reason": "exact_current",
    "requested": {
      "commit_sha": null,
      "git_ref": null,
      "kind": "repo_default_branch",
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "resolved_requested": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "served": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    }
  },
  "total": 1
}

{
  "code": "VALIDATION_ERROR",
  "detail": "The request is invalid.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 400,
  "title": "Validation error",
  "type": "about:blank"
}

{
  "code": "AUTHENTICATION_REQUIRED",
  "detail": "A bearer credential is required.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 401,
  "title": "Authentication required",
  "type": "about:blank"
}

{
  "code": "FORBIDDEN",
  "detail": "The caller is not allowed to access this resource.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 403,
  "title": "Forbidden",
  "type": "about:blank"
}

{
  "code": "PACKAGE_NOT_FOUND",
  "detail": "The requested package was not found.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 404,
  "title": "Package not found",
  "type": "about:blank"
}

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

{
  "code": "UNSUPPORTED_PACKAGE_VARIANTS",
  "detail": "The package release has unsupported artifact variants.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 422,
  "title": "Unsupported package variants",
  "type": "about:blank"
}

{
  "code": "RATE_LIMITED",
  "detail": "The request was rate limited.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 429,
  "title": "Rate limited",
  "type": "about:blank"
}

{
  "code": "UPSTREAM_ERROR",
  "detail": "The upstream service failed to provide a response.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 502,
  "title": "Upstream error",
  "type": "about:blank"
}

{
  "code": "PACKAGE_INDEXING",
  "detail": "Code evidence is not ready; retry the request later.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 503,
  "title": "Code indexing",
  "type": "about:blank"
}

{
  "code": "TIMEOUT",
  "detail": "The upstream request did not complete in time.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 504,
  "title": "Upstream timeout",
  "type": "about:blank"
}

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

registry

enum<string>

Package registry, required with name; mutually exclusive with repo_url.

Available options:

npm,

pypi,

hex,

crates,

vcpkg,

zig,

nuget,

maven,

packagist,

rubygems,

go,

swift

name

string

Package name (max 255 bytes), including encoded scoped names such as %40scope%2Fpackage.

Minimum string length: 1

version

string

Optional package version (max 100 bytes); forbidden with repo_url. Omission retains latest release intent.

Minimum string length: 1

repo_url

string

Public GitHub, GitLab, or Codeberg repository root URL. HTTPS and git+https are supported on all three; GitHub also accepts http, git, ssh, and git+ssh. Use default transport ports and omit credentials, query strings, and fragments. GitLab nested groups are supported. Use HTTPS instead of scp-style shorthand.

Minimum string length: 1

git_ref

string

Repository-only branch, tag or SHA. Omission preserves default-branch intent; no implicit HEAD.

Minimum string length: 1

path

string

Exact target-relative selector, OR-ed with path_prefix and globs.

Minimum string length: 1

path_prefix

string

Literal target-relative prefix, OR-ed with path/globs. Root-only dot means omitted. Trailing slash retains directory boundary.

Minimum string length: 1

file_intent

enum<string>

Single inclusive intent; forbidden with file_intents.

Available options:

production,

test,

benchmark,

example,

generated,

fixture,

build,

vendor

exclude_doc_files

boolean

default:false

Exclude source-classified documentation after inclusive filtering.

exclude_test_files

boolean

default:false

Exclude source-classified tests after inclusive filtering.

include_hidden

boolean

default:false

Include dotfiles and files under dot-prefixed path segments (default false).

limit

integer

default:200

Maximum files per page: 1–1000, default 200. A smaller page does not reduce file enumeration work.

Required range: 1 <= x <= 1000

offset

integer

default:0

Nonnegative offset into all matching paths, default zero. Pin served artifact across pages.

Required range: 0 <= x <= 2147483647

wait_timeout_ms

integer

default:20000

Time to wait for indexing: 0–60000 milliseconds, default 20000. Zero returns immediately; if files are not ready, the response is 503 PACKAGE_INDEXING.

Required range: 0 <= x <= 60000

globs

string[]

Repeatable OR-ed glob selectors; commas and braces remain literal glob text. At most 1000 path + globs selectors.

Minimum array length: 1

Minimum string length: 1

extensions

string[]

Repeat for each case-insensitive extension, without leading dot. AND with inclusion selectors.

Minimum array length: 1

Minimum string length: 1

file_types

string[]

Repeat for each source file-type filter; values within this family are OR-ed.

Minimum array length: 1

Minimum string length: 1

languages

string[]

Repeat for each source language filter; values within this family are OR-ed.

Minimum array length: 1

Minimum string length: 1

file_intents

enum<string>[]

Repeat for inclusive intents; forbidden with file_intent.

Minimum array length: 1

Available options:

production,

test,

benchmark,

example,

generated,

fixture,

build,

vendor

exclude_file_intents

enum<string>[]

Repeat for intents excluded after inclusive filtering.

Minimum array length: 1

Available options:

production,

test,

benchmark,

example,

generated,

fixture,

build,

vendor

Response

Sorted matching file page

One source inventory page and the exact evidence qualification.

code_index_state

enum<string>

required

Freshness of the served code inventory.

Available options:

current,

stale,

provisional

files

object[]

required

Atomic rows sorted by target-relative path ascending.

Show child attributes

indexing_ref

string | null

required

Opaque active indexing reference, including refresh of stale or provisional evidence; null when absent.

limit

integer<int32>

required

Effective page cap, 1 through 1000 (default 200).

offset

integer<int32>

required

Requested nonnegative offset into the sorted filtered inventory.

returned

integer

required

Number of rows in this page.

Required range: x >= 0

target_resolution

object

required

Canonical requested, resolved and served provenance reported by the source.

Show child attributes

total

integer<int64>

required

All matching files across every page.

Required range: x >= 0

⌘I

GET /v1/code/files?registry=npm&name=%40scope%2Fpackage HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>

{
  "code_index_state": "current",
  "files": [
    {
      "byte_size": 0,
      "file_type": "source",
      "language": "rust",
      "name": "main.rs",
      "path": "src/main.rs"
    }
  ],
  "indexing_ref": null,
  "limit": 200,
  "offset": 0,
  "returned": 1,
  "target_resolution": {
    "freshness": "current",
    "freshness_reason": "exact_current",
    "requested": {
      "commit_sha": null,
      "git_ref": null,
      "kind": "repo_default_branch",
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "resolved_requested": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "served": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    }
  },
  "total": 1
}

{
  "code": "VALIDATION_ERROR",
  "detail": "The request is invalid.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 400,
  "title": "Validation error",
  "type": "about:blank"
}

{
  "code": "AUTHENTICATION_REQUIRED",
  "detail": "A bearer credential is required.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 401,
  "title": "Authentication required",
  "type": "about:blank"
}

{
  "code": "FORBIDDEN",
  "detail": "The caller is not allowed to access this resource.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 403,
  "title": "Forbidden",
  "type": "about:blank"
}

{
  "code": "PACKAGE_NOT_FOUND",
  "detail": "The requested package was not found.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 404,
  "title": "Package not found",
  "type": "about:blank"
}

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

{
  "code": "UNSUPPORTED_PACKAGE_VARIANTS",
  "detail": "The package release has unsupported artifact variants.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 422,
  "title": "Unsupported package variants",
  "type": "about:blank"
}

{
  "code": "RATE_LIMITED",
  "detail": "The request was rate limited.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 429,
  "title": "Rate limited",
  "type": "about:blank"
}

{
  "code": "UPSTREAM_ERROR",
  "detail": "The upstream service failed to provide a response.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 502,
  "title": "Upstream error",
  "type": "about:blank"
}

{
  "code": "PACKAGE_INDEXING",
  "detail": "Code evidence is not ready; retry the request later.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 503,
  "title": "Code indexing",
  "type": "about:blank"
}

{
  "code": "TIMEOUT",
  "detail": "The upstream request did not complete in time.",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "status": 504,
  "title": "Upstream timeout",
  "type": "about:blank"
}

Get started

v1 reference

List package or repository code files

Authorizations

Headers

Query Parameters

Response