GitHits API

openapi: 3.1.0
info:
  title: GitHits API
  version: '2026-11-10'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-10: 21 operation(s) read from 13 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; GitHits has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 12
    documentation: 9
    pages-with-code: 9
    pages-read: 13
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-10'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.githits.com/api/errors.md
  - https://api.githits.dev/v1/openapi.json
  - https://docs.githits.com/api/quickstart
  - https://docs.githits.com/api/versioning
  - https://docs.githits.com/api/quickstart.md
  - https://docs.githits.com/api/versioning.md
  - https://docs.githits.com/api/lockfile-analysis
  - https://docs.githits.com/api/lockfile-analysis.md
  - https://docs.githits.com/api/requests-and-responses
  - https://docs.githits.com/api/requests-and-responses.md
  - https://docs.githits.com/api-reference/v1/packages/review-package-upgrades
  - https://docs.githits.com/api-reference/v1/experimental/resolve-a-target-name
  - https://docs.githits.com/api-reference/v1/packages/inspect-package-dependencies
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://docs.githits.com/api/lockfile-analysis
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --fail-with-body --silent --show-error --no-buffer  --header \"Authorization: Bearer $GITHITS_API_TOKEN \"  --header 'Accept:\
          \ text/event-stream'  \"https://api.githits.dev $EVENTS_URL \" \n Apply each snapshot event as a complete state replacement. Revisions\
          \ are nondecreasing but can repeat: state or attempt can change at the same revision. If the stream closes before a terminal snapshot,\
          \ reconnec"
  /api-reference/v1/experimental/submit-a-lockfile-analysis-job.md:
    get:
      operationId: get_api_reference_v1_experimental_submit_a_lockfile_analysis_job_md
      tags:
      - Api Reference
      summary: GET /api-reference/v1/experimental/submit-a-lockfile-analysis-job.md
      x-source: https://docs.githits.com/api/lockfile-analysis.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl's exit status before using `job.json`. With `--fail-with-body`, an HTTP failure saves a problem response there. A successful
          [submission response](https://docs.githits.com/api-reference/v1/experimental/submit-a-lockfile-analysis-job.md) includes `id`, `state`,
          `expires_at`, `status_url`, `events_url` and `result_url`. Retain these values. The URLs are relative to `https://api.githits.dev`.
  /api/quickstart.md:
    get:
      operationId: get_api_quickstart_md
      tags:
      - Api
      summary: GET /api/quickstart.md
      x-source: https://docs.githits.com/api/errors.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl quickstart](https://docs.githits.com/api/quickstart.md) in your own terminal. The API does not allow those other sites to
          send playground requests.
  /v1/changelog:
    get:
      operationId: get_v1_changelog
      tags:
      - Changelog
      summary: GET /v1/changelog
      x-source: https://api.githits.dev/v1/openapi.json
      parameters:
      - name: registry
        in: query
        required: false
        schema:
          type: string
        description: Canonical lowercase registry, required together with name and mutually exclusive with repo_url. Same registry set as package
          inspection.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/code/diff:
    post:
      operationId: post_v1_code_diff
      tags:
      - Code
      summary: Use POST /v1/code/diff for source comparisons.
      x-source: https://docs.githits.com/api/versioning
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/experimental/license-reports:
    get:
      operationId: get_v1_experimental_license_reports
      tags:
      - Experimental
      summary: GET /v1/experimental/license-reports
      x-source: https://docs.githits.com/api/lockfile-analysis
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --fail-with-body --silent --show-error  --header \"Authorization: Bearer $GITHITS_API_TOKEN \"  --output license-report.json\
          \  \"https://api.githits.dev/v1/experimental/license-reports/ $JOB_ID \" \n The successful response is the compact JSON report with\
          \ schema_version: 2 . This read uses the existing analysis, with the same authorization and expiry; it does not start another analysis.\
          \ Check curl’"
    post:
      operationId: post_v1_experimental_license_reports
      tags:
      - Experimental
      summary: Synchronously generate a license report (experimental)
      description: Alternative synchronous endpoint for license report generation. Experimental and likely to be removed.
      x-source: https://docs.githits.com/api/lockfile-analysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ExperimentalLicenseReportsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ExperimentalLicenseReportsResponse'
      x-evidence:
        kind: documentation
  /v1/experimental/license-reports/{id}:
    get:
      operationId: get_v1_experimental_license_reports_id
      tags:
      - Experimental
      summary: Preview a compact report for a completed analysis
      description: Returns the compact JSON license report for a completed SBOM job. Requires a finished CycloneDX SBOM job; other job types return
        409 errors.
      x-source: https://docs.githits.com/api/lockfile-analysis
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ExperimentalLicenseReportsIdResponse'
      x-evidence:
        kind: documentation
  /v1/experimental/licenses:
    post:
      operationId: post_v1_experimental_licenses
      tags:
      - Experimental
      summary: Synchronously generate a license report (experimental)
      description: Synchronous endpoint to generate a compact license report. Experimental and likely to be removed.
      x-source: https://docs.githits.com/api/lockfile-analysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ExperimentalLicensesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ExperimentalLicensesResponse'
      x-evidence:
        kind: documentation
  /v1/experimental/licenses/{id}:
    get:
      operationId: get_v1_experimental_licenses_id
      tags:
      - Experimental
      summary: Legacy read of a license report (schema 1)
      description: Legacy endpoint returning the older license report schema. Use the compact schema‑2 endpoint instead.
      x-source: https://docs.githits.com/api/lockfile-analysis
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ExperimentalLicensesIdResponse'
      x-evidence:
        kind: documentation
  /v1/experimental/lockfile-jobs:
    get:
      operationId: get_v1_experimental_lockfile_jobs
      tags:
      - Experimental
      summary: GET /v1/experimental/lockfile-jobs
      x-source: https://docs.githits.com/api/lockfile-analysis
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
      - name: kind
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --fail-with-body --silent --show-error  --header \"Authorization: Bearer $GITHITS_API_TOKEN \"  --form 'files[]=@Cargo.toml;filename=Cargo.toml'\
          \  --form 'files[]=@Cargo.lock;filename=Cargo.lock'  --output job.json  'https://api.githits.dev/v1/experimental/lockfile-jobs?kind=sbom&format=cyclonedx'\
          \ \n Choose the format at submission; Accept does not select it: \n format Download cyclonedx (default)"
    post:
      operationId: post_v1_experimental_lockfile_jobs
      tags:
      - Experimental
      summary: Submit an SBOM, audit or license‑report job
      description: Upload manifests and lockfiles to generate SBOMs, audit dependencies or read compact license reports through the experimental
        REST API. Returns HTTP 202 with job details.
      x-source: https://docs.githits.com/api/lockfile-analysis
      parameters:
      - name: kind
        in: query
        required: true
        schema:
          type: string
        description: Type of analysis to run – sbom, audit or sbom (for license report).
      - name: format
        in: query
        required: true
        schema:
          type: string
        description: Output format – cyclonedx, spdx or text for SBOM; json for audit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ExperimentalLockfileJobsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ExperimentalLockfileJobsResponse'
      x-evidence:
        kind: documentation
  /v1/experimental/research:
    post:
      operationId: post_v1_experimental_research
      tags:
      - Experimental
      summary: POST /v1/experimental/research
      x-source: https://docs.githits.com/api/requests-and-responses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ExperimentalResearchRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --silent --show-error --max-time 240  --header \"Authorization: Bearer $GITHITS_API_TOKEN \"  --header 'Content-Type: application/json'\
          \  --data '{\"target\":{\"registry\":\"npm\",\"name\":\"express\",\"version\":\"5.1.0\"},\"question\":\"How does error handling work?\"\
          }'  'https://api.githits.dev/v1/experimental/research' \n The response contains answer_markdown , ordered sources with URLs, a tool_call_id\
          \ for dia"
  /v1/experimental/sbom:
    post:
      operationId: post_v1_experimental_sbom
      tags:
      - Experimental
      summary: Synchronously generate an SBOM (experimental)
      description: Synchronous endpoint to generate an SBOM directly. Marked experimental and likely to be removed.
      x-source: https://docs.githits.com/api/lockfile-analysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ExperimentalSbomRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ExperimentalSbomResponse'
      x-evidence:
        kind: documentation
  /v1/experimental/targets/resolve:
    post:
      operationId: post_v1_experimental_targets_resolve
      tags:
      - Experimental
      summary: POST /v1/experimental/targets/resolve
      x-source: https://docs.githits.com/api-reference/v1/experimental/resolve-a-target-name
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl package curl --request POST  --url https://api.githits.dev/v1/experimental/targets/resolve  --header 'Authorization: Bearer\
          \ <token>'  --header 'Content-Type: application/json'  --data ' \n { \n \"limit\": 8, \n \"name\": \"Phoenix\", \n \"preferred_kind\"\
          : \"package\", \n \"query\": \"web framework\", \n \"registries\": [ \n \"hex\" \n ] \n } \n ' 200 ambiguous { \n \"ambiguous\" : true\
          \ , \n \"ambiguous_reason\" : \"duplicate_"
  /v1/list:
    post:
      operationId: post_v1_list
      tags:
      - List
      summary: POST /v1/list
      x-source: https://docs.githits.com/api/quickstart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ListRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --silent --show-error  --header \"Authorization: Bearer $GITHITS_API_TOKEN \"  --header 'Content-Type: application/json'\
          \  --data '{\"target\":\"npm:express@4.18.2\",\"limit\":20,\"wait_timeout_ms\":20000}'  'https://api.githits.dev/v1/list' \n Follow\
          \ an entry’s read action with its exact target and non-null path at GET /v1/read . Preserve those values instead of constructing a path\
          \ from its display name"
  /v1/package-upgrade-reviews:
    get:
      operationId: get_v1_package_upgrade_reviews
      tags:
      - Package Upgrade Reviews
      summary: GET /v1/package-upgrade-reviews
      x-source: https://docs.githits.com/api-reference/v1/packages/review-package-upgrades
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1PackageUpgradeReviewsResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl);\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n} package main\nimport (\n \"fmt\"\n \"strings\"\
          \n \"net/http\"\n \"io\"\n)\nfunc main() {\n url := \"https://api.githits.dev/v1/package-upgrade-reviews\"\n payload := strings.NewReader(\"\
          {\\n \\\"packages\\\": [\\n {\\n \\\"current_version\\\": \\\"1.0.0\\\",\\n \\\"name\\\": \\\"example\\\",\\n \\\"registry\\\": \\\"\
          npm\\\",\\n \\\"target_version\\\": \\\"2.0.0\\\"\\n }\\n ]\\n}\")\n req"
    post:
      operationId: post_v1_package_upgrade_reviews
      tags:
      - Package Upgrade Reviews
      summary: POST /v1/package-upgrade-reviews
      x-source: https://docs.githits.com/api-reference/v1/packages/review-package-upgrades
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1PackageUpgradeReviewsResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl curl --request POST  --url https://api.githits.dev/v1/package-upgrade-reviews  --header 'Authorization: Bearer <token>'\
          \  --header 'Content-Type: application/json'  --data '\n{\n \"packages\": [\n {\n \"current_version\": \"1.0.0\",\n \"name\": \"example\"\
          ,\n \"registry\": \"npm\",\n \"target_version\": \"2.0.0\"\n }\n ]\n}\n' import requests\nurl = \"https://api.githits.dev/v1/package-upgrade-reviews\"\
          \npayload = { \"packages"
  /v1/packages/npm/express:
    get:
      operationId: get_v1_packages_npm_express
      tags:
      - Packages
      summary: GET /v1/packages/npm/express
      x-source: https://docs.githits.com/api/quickstart
      parameters:
      - name: version
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --silent --show-error --include  --header \"Authorization: Bearer $GITHITS_API_TOKEN \"  'https://api.githits.dev/v1/packages/npm/express?version=4.18.2'\
          \ \n A successful request returns HTTP 200 with JSON containing package and selected_version . The package identity includes its latest\
          \ version; selected_version describes the requested release, 4.18.2 . Keep that version information with the res"
  /v1/packages/npm/express/dependencies:
    get:
      operationId: get_v1_packages_npm_express_dependencies
      tags:
      - Packages
      summary: GET /v1/packages/npm/express/dependencies
      description: Explore the dependencies of a package release, from its direct dependencies to the full dependency graph.
      x-source: https://docs.githits.com/api-reference/v1/packages/inspect-package-dependencies
      parameters:
      - name: version
        in: query
        required: false
        schema:
          type: string
        description: Concrete version or source-supported constraint; omitted/blank uses the registry's default install selection.
      - name: lifecycle
        in: query
        required: false
        schema:
          type: string
        description: Requires dependencies.groups selection. Comma-separated runtime (default), development, build, peer, optional, all.
      - name: max_depth
        in: query
        required: false
        schema:
          type: string
        description: Optional maximum dependency depth, from 1 to 10. Requires transitive, importers or issues selection.
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated atomic selectors from the catalogue; explicit selection replaces default direct+groups.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1PackagesNpmExpressDependenciesResponse'
      x-evidence:
        kind: documentation
  /v1/read:
    get:
      operationId: get_v1_read
      tags:
      - Read
      summary: Follow an entry’s read action with its exact target and non‑null path
      description: Use the read endpoint to retrieve documentation or source code for a given target and path as returned by the list endpoint.
        The response’s kind identifies documentation or code.
      x-source: https://docs.githits.com/api/quickstart
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostV1ExperimentalLicenseReportsRequest:
      type: object
      properties:
        files[]:
          type: string
          description: Manifest and/or lockfile files.
      required:
      - files[]
    PostV1ExperimentalLicenseReportsResponse:
      type: object
      properties:
        report:
          type: object
          description: Compact license report.
    GetV1ExperimentalLicenseReportsIdResponse:
      type: object
      properties:
        schema_version:
          type: integer
          description: Version of the compact report schema (2).
        inventory:
          type: object
          description: Input and coverage context.
        components:
          type: array
          description: List of components with license evidence.
    PostV1ExperimentalLicensesRequest:
      type: object
      properties:
        files[]:
          type: string
          description: Manifest and/or lockfile files.
      required:
      - files[]
    PostV1ExperimentalLicensesResponse:
      type: object
      properties:
        report:
          type: object
          description: Compact license report.
    GetV1ExperimentalLicensesIdResponse:
      type: object
      properties:
        schema_version:
          type: integer
          description: Version of the legacy report schema (1).
        report:
          type: object
          description: License report data.
    PostV1ExperimentalLockfileJobsRequest:
      type: object
      properties:
        files[]:
          type: string
          description: One or more UTF‑8 manifest or lockfile files, sent as repeated multipart parts.
      required:
      - files[]
    PostV1ExperimentalLockfileJobsResponse:
      type: object
      properties:
        id:
          type: string
          description: Job identifier.
        state:
          type: string
          description: Current job state.
        expires_at:
          type: string
          description: Expiration timestamp.
        status_url:
          type: string
          description: Relative URL to poll job status.
        events_url:
          type: string
          description: Relative URL for server‑sent event stream.
        result_url:
          type: string
          description: Relative URL to download the final result (SBOM or audit).
    PostV1ExperimentalResearchRequest:
      type: object
      properties:
        target:
          type: object
          properties:
            registry:
              type: string
            name:
              type: string
            version:
              type: string
        question:
          type: string
    PostV1ExperimentalSbomRequest:
      type: object
      properties:
        files[]:
          type: string
          description: Manifest and/or lockfile files.
        format:
          type: string
          description: Desired SBOM format (cyclonedx, spdx, text).
      required:
      - files[]
      - format
    PostV1ExperimentalSbomResponse:
      type: object
      properties:
        bom:
          type: string
          description: Generated SBOM document.
    PostV1ListRequest:
      type: object
      properties:
        target:
          type: string
        limit:
          type: integer
        wait_timeout_ms:
          type: integer
    GetV1PackageUpgradeReviewsResponse:
      type: object
      properties:
        breaking_signals:
          type: array
          items: {}
        entries:
          type: array
          items:
            type: object
            properties:
              body:
                type: string
              body_preview:
                type: string
              detail_source:
                type: string
              has_changelog:
                type: boolean
              headline:
                type: string
              html_url:
                type:
                - string
                - 'null'
              published_at:
                type:
                - string
                - 'null'
              signals:
                type: array
                items: {}
              source_version:
                type: string
              version:
                type: string
        fallback:
          type:
          - string
          - 'null'
        has_release_note_bodies:
          type: boolean
        keyword_entries:
          type: array
          items: {}
        migration_signals:
          type: array
          items: {}
        source:
          type: string
        total_entries:
          type: integer
        total_entries_with_bodies:
          type: integer
        total_keyword_entries:
          type: integer
        truncated:
          type: boolean
    PostV1PackageUpgradeReviewsResponse:
      type: object
      properties:
        breaking_signals:
          type: array
          items: {}
        entries:
          type: array
          items:
            type: object
            properties:
              body:
                type: string
              body_preview:
                type: string
              detail_source:
                type: string
              has_changelog:
                type: boolean
              headline:
                type: string
              html_url:
                type:
                - string
                - 'null'
              published_at:
                type:
                - string
                - 'null'
              signals:
                type: array
                items: {}
              source_version:
                type: string
              version:
                type: string
        fallback:
          type:
          - string
          - 'null'
        has_release_note_bodies:
          type: boolean
        keyword_entries:
          type: array
          items: {}
        migration_signals:
          type: array
          items: {}
        source:
          type: string
        total_entries:
          type: integer
        total_entries_with_bodies:
          type: integer
        total_keyword_entries:
          type: integer
        truncated:
          type: boolean
    GetV1PackagesNpmExpressDependenciesResponse:
      type: object
      properties:
        analysis:
          type: object
          description: Applied scope retained independently of selected output groups.
        dependencies:
          type: object
          description: Only selected, available evidence groups are serialized.
        package:
          type: object
          description: Resolved root identity; version is null when no release was inspected.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Api Reference
- name: Changelog
- name: Code
- name: Experimental
- name: List
- name: Package Upgrade Reviews
- name: Packages
- name: Read