> ## 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. # Get dependency licenses for a completed analysis > Retrieve a JSON license report for an analysis job you can access. Use the analysis `id` returned in the HTTP 202 submission response. The synchronous `POST /v1/experimental/licenses` response has no job ID; a component's `bom_ref` cannot be used here. The job must have been submitted with `kind=sbom&format=cyclonedx`. You do not need to parse a CycloneDX document to use this JSON report. An audit job or a job using SPDX/text output returns 409 `INCOMPATIBLE_ANALYSIS`; choose a compatible job or submit a new one with the required parameters. **Create and follow a job** Use a GitHits Bearer credential for an active account with required terms accepted. In these examples, `/path/to/private-auth.conf` is your own protected curl configuration containing `header = "Authorization: Bearer "`; replace the placeholder privately and keep the file outside your repository. ```sh curl --config /path/to/private-auth.conf \ --fail-with-body --silent --show-error \ --form 'files[]=@package.json;filename=package.json' \ --form 'files[]=@package-lock.json;filename=package-lock.json' \ --output job.json \ 'https://api.githits.dev/v1/experimental/lockfile-jobs?kind=sbom&format=cyclonedx' ``` 1. Check for HTTP 202 and read `id` from `job.json`. Keep `expires_at` and the returned links. 2. Resolve `status_url` or `events_url` against the API server URL. Read status or consume the server-sent events until `state=succeeded`. The presence of `result_url` alone does not mean the job is ready. On `state=failed`, inspect the job status's `error` code before deciding whether to submit new work; a licenses read also returns 409 `ANALYSIS_FAILED` with `failure_code`. 3. Replace `{id}` below with the submission response's `id` and request the licenses view: ```sh curl --config /path/to/private-auth.conf \ --fail-with-body --silent --show-error \ --output licenses.json \ 'https://api.githits.dev/v1/experimental/licenses/{id}' ``` On HTTP 200, `licenses.json` contains `schema_version`, `inventory` and `components`. On an HTTP error, curl exits unsuccessfully and saves a JSON problem in that file; check the exit status before treating it as a report. No query parameters or `Accept`-based format selection are supported. Reading this report does not start another analysis or reserve another set of analysis units. Submitting a new job is a new analysis (currently 100 weighted daily units at default policy). The `x-githits-cost` value for this read is 0. Keep using the same ID for reads until the job expires instead of resubmitting just to retrieve the report. **Interpret the response** Every reported project, dependency or file/source entry remains separate, including repeated names, versions or package URLs. Use `bom_ref` for reported relationships and `properties` for input paths. `licenses` gives license choices; `observed_licenses` gives independent observations. `publisher_evidence` retains original publisher statements and release/package/repository context. `source_evidence` retains source-file paths, detected licenses and observation/attempt history. Both evidence fields are JSON objects already. Some named `properties[].value` strings contain extra JSON that you parse separately; the field descriptions identify them. Null means the corresponding information was unavailable. Empty arrays do not prove that no license exists, that all files were checked, or that the dependency graph is complete. Read `inventory.completeness` with the component list. Dependency coverage is in `inventory.compositions` and the `inventory.properties` entry named `githits:dependency_coverage`; parse that entry's `value` as JSON. Notices are properties named `githits:notice`. No chosen license, AND/OR relationship between separate choices, or pass/fail decision is added. New string values and fields can appear; preserve or ignore unfamiliar data instead of rejecting an otherwise usable report. **Handle errors** Problems use `application/problem+json`; branch on `code` and keep `X-Request-ID` for support. | Status / code | What to do | | --- | --- | | 400 `VALIDATION_ERROR` / `INVALID_SESSION_ID` | Remove query parameters or correct the session header/field identified in `detail`. | | 401 / 403 | Check the credential, account access and required terms; use any provided terms/acceptance links. | | 404 `ANALYSIS_NOT_FOUND` | Check the submission ID and credential. Missing, expired and inaccessible jobs have the same response. A result that is no longer stored requires a new submission if you still need it. | | 409 `ANALYSIS_PENDING` | Wait for completion through status/events, then retry this GET; do not submit a second job just to wait. | | 409 `ANALYSIS_FAILED` | Inspect `failure_code` and the job status. Correct the input or cause before deliberately creating another analysis. | | 409 `INCOMPATIBLE_ANALYSIS` | Use a job created with `kind=sbom&format=cyclonedx`; the format of an existing job cannot be changed by this GET. | | 422 `LICENSE_REPORT_TOO_LARGE` | The JSON report exceeds 16,777,216 bytes. Download the job's original CycloneDX document through `result_url`, or create a smaller analysis if appropriate. Jobs do not raise the report-size limit. | | 429 `RATE_LIMITED` | Respect `Retry-After` when provided. | | 502 `UPSTREAM_ERROR` | The analysis result could not be read. Keep the job ID and `X-Request-ID`, and report a persistent failure; do not repeatedly resubmit the same files. | | 503 / 504 | Try reading the same job again later. This does not start another analysis. | Responses must not be cached (`Cache-Control: no-store`). The report does not certify an installed artifact or complete license coverage. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json get /v1/experimental/licenses/{id} 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 or source code | Browse with list, then follow an exact action through the unified read operation | | Browse known content | List source files, local documentation, or an explicit hosted site | | Find exact text | Grep across ordered packages, repositories and hosted sites, then follow exact read actions | | 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 | | Research 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 | | Report dependency licenses | Upload manifests/lockfiles or use a completed analysis to read license choices, source observations and coverage for each reported entry | | Generate an SBOM | Upload manifests and lockfiles to receive a CycloneDX, SPDX or text inventory | | Audit lockfiles | Submit asynchronous audit analysis, follow status or SSE, then download findings and independent coverage as JSON | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.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`. Standard SBOM documents and embedded standard objects in licenses reports retain their format's field names. Percent-encode path parameters such as package names as one path segment, including any embedded slash. The unified read target is a query value: encode a literal plus sign as `%2B` and a literal fragment marker as `%23`; 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`; job events use `no-store, no-transform` to preserve streaming. When available, successful and rate-limited responses from operations that document them include `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for the shared usage window. All three header values must be available; a credential type alone does not guarantee these headers. Reset is an absolute Unix epoch timestamp in seconds (UTC), rounded up, not a delay. These snapshots support pacing; concurrent requests and other quotas can still cause 429. Honor `Retry-After` when supplied. The trio is omitted when usage metadata is unavailable, and is not exposed for generated examples, Research, feedback, language discovery, SBOM/licenses generation and licenses views, or job submission, events and results. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Research, 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: >- Current source-advisory evidence by ID, independent of package-version assessment. name: Vulnerabilities - description: >- Find exact text across ordered source and hosted-documentation scopes, check coverage, and follow exact reads. name: Grep - description: >- Browse package, repository or hosted-site paths and follow exact read and browse actions. name: List - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Read an exact documentation page or source file and retain the page, package-version or repository-commit details needed to cite it. name: Read - 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: Stable exact-tree source comparison. name: Code Diff - description: >- Preview target resolution, cited questions and SBOM generation, plus the deprecated source comparison alias. Use /v1/code/diff for stable source comparison. name: Experimental paths: /v1/experimental/licenses/{id}: get: tags: - Experimental summary: Get dependency licenses for a completed analysis description: > Retrieve a JSON license report for an analysis job you can access. Use the analysis `id` returned in the HTTP 202 submission response. The synchronous `POST /v1/experimental/licenses` response has no job ID; a component's `bom_ref` cannot be used here. The job must have been submitted with `kind=sbom&format=cyclonedx`. You do not need to parse a CycloneDX document to use this JSON report. An audit job or a job using SPDX/text output returns 409 `INCOMPATIBLE_ANALYSIS`; choose a compatible job or submit a new one with the required parameters. **Create and follow a job** Use a GitHits Bearer credential for an active account with required terms accepted. In these examples, `/path/to/private-auth.conf` is your own protected curl configuration containing `header = "Authorization: Bearer "`; replace the placeholder privately and keep the file outside your repository. ```sh curl --config /path/to/private-auth.conf \ --fail-with-body --silent --show-error \ --form 'files[]=@package.json;filename=package.json' \ --form 'files[]=@package-lock.json;filename=package-lock.json' \ --output job.json \ 'https://api.githits.dev/v1/experimental/lockfile-jobs?kind=sbom&format=cyclonedx' ``` 1. Check for HTTP 202 and read `id` from `job.json`. Keep `expires_at` and the returned links. 2. Resolve `status_url` or `events_url` against the API server URL. Read status or consume the server-sent events until `state=succeeded`. The presence of `result_url` alone does not mean the job is ready. On `state=failed`, inspect the job status's `error` code before deciding whether to submit new work; a licenses read also returns 409 `ANALYSIS_FAILED` with `failure_code`. 3. Replace `{id}` below with the submission response's `id` and request the licenses view: ```sh curl --config /path/to/private-auth.conf \ --fail-with-body --silent --show-error \ --output licenses.json \ 'https://api.githits.dev/v1/experimental/licenses/{id}' ``` On HTTP 200, `licenses.json` contains `schema_version`, `inventory` and `components`. On an HTTP error, curl exits unsuccessfully and saves a JSON problem in that file; check the exit status before treating it as a report. No query parameters or `Accept`-based format selection are supported. Reading this report does not start another analysis or reserve another set of analysis units. Submitting a new job is a new analysis (currently 100 weighted daily units at default policy). The `x-githits-cost` value for this read is 0. Keep using the same ID for reads until the job expires instead of resubmitting just to retrieve the report. **Interpret the response** Every reported project, dependency or file/source entry remains separate, including repeated names, versions or package URLs. Use `bom_ref` for reported relationships and `properties` for input paths. `licenses` gives license choices; `observed_licenses` gives independent observations. `publisher_evidence` retains original publisher statements and release/package/repository context. `source_evidence` retains source-file paths, detected licenses and observation/attempt history. Both evidence fields are JSON objects already. Some named `properties[].value` strings contain extra JSON that you parse separately; the field descriptions identify them. Null means the corresponding information was unavailable. Empty arrays do not prove that no license exists, that all files were checked, or that the dependency graph is complete. Read `inventory.completeness` with the component list. Dependency coverage is in `inventory.compositions` and the `inventory.properties` entry named `githits:dependency_coverage`; parse that entry's `value` as JSON. Notices are properties named `githits:notice`. No chosen license, AND/OR relationship between separate choices, or pass/fail decision is added. New string values and fields can appear; preserve or ignore unfamiliar data instead of rejecting an otherwise usable report. **Handle errors** Problems use `application/problem+json`; branch on `code` and keep `X-Request-ID` for support. | Status / code | What to do | | --- | --- | | 400 `VALIDATION_ERROR` / `INVALID_SESSION_ID` | Remove query parameters or correct the session header/field identified in `detail`. | | 401 / 403 | Check the credential, account access and required terms; use any provided terms/acceptance links. | | 404 `ANALYSIS_NOT_FOUND` | Check the submission ID and credential. Missing, expired and inaccessible jobs have the same response. A result that is no longer stored requires a new submission if you still need it. | | 409 `ANALYSIS_PENDING` | Wait for completion through status/events, then retry this GET; do not submit a second job just to wait. | | 409 `ANALYSIS_FAILED` | Inspect `failure_code` and the job status. Correct the input or cause before deliberately creating another analysis. | | 409 `INCOMPATIBLE_ANALYSIS` | Use a job created with `kind=sbom&format=cyclonedx`; the format of an existing job cannot be changed by this GET. | | 422 `LICENSE_REPORT_TOO_LARGE` | The JSON report exceeds 16,777,216 bytes. Download the job's original CycloneDX document through `result_url`, or create a smaller analysis if appropriate. Jobs do not raise the report-size limit. | | 429 `RATE_LIMITED` | Respect `Retry-After` when provided. | | 502 `UPSTREAM_ERROR` | The analysis result could not be read. Keep the job ID and `X-Request-ID`, and report a persistent failure; do not repeatedly resubmit the same files. | | 503 / 504 | Try reading the same job again later. This does not start another analysis. | Responses must not be cached (`Cache-Control: no-store`). The report does not certify an installed artifact or complete license coverage. operationId: get_dependency_licenses parameters: - description: >- Analysis id returned in the HTTP 202 JSON response from POST /v1/experimental/lockfile-jobs?kind=sbom&format=cyclonedx. Use a credential that can access that job, such as the credential used to submit it. A component bom_ref is not a job id. Missing, malformed, expired or inaccessible ids return ANALYSIS_NOT_FOUND after authentication. in: path name: id required: true schema: 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 caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created. in: header name: X-GitHits-Session-ID required: false schema: maxLength: 64 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,64}$ type: string responses: '200': content: application/json: example: components: - bom_ref: root external_references: [] hashes: [] licenses: - acknowledgement: declared expression: MIT name: project observed_licenses: [] properties: - name: githits:record_kind value: manifest - name: githits:manifest_path value: package.json publisher_evidence: null purl: null record_kind: manifest scope: null source_evidence: null type: library version: null - bom_ref: a external_references: - hashes: - alg: SHA-256 content: reference-digest type: vcs url: https://example.com/source - type: distribution url: https://example.com/artifact.tgz hashes: - alg: SHA-256 content: package-digest licenses: - acknowledgement: declared expression: MIT future_choice: true - license: name: Opaque publisher terms name: dependency observed_licenses: [] properties: - name: githits:record_kind value: locked_package - name: githits:lockfile_path value: one/package-lock.json - name: githits:license_artifact_verification value: not_checked publisher_evidence: capture_status: present controlling_index: 0 coverage: complete display_value: MIT expression: MIT observations: - interpretation: expression: MIT interpretation_methods: - spdx_expression issues: [] status: expression syntax: spdx observation: field: license relation: single scope: release source: npm_registry statements: - MIT status: present version: 1.0.0 relationship: controlling reason: publisher_release_metadata status: expression purl: pkg:npm/dependency@1.0.0 record_kind: locked_package scope: excluded source_evidence: null type: library version: 1.0.0 - bom_ref: b external_references: - hashes: - alg: SHA-256 content: reference-digest type: vcs url: https://example.com/source - type: distribution url: https://example.com/artifact.tgz hashes: - alg: SHA-256 content: package-digest licenses: - acknowledgement: declared expression: MIT future_choice: true - license: name: Opaque publisher terms name: dependency observed_licenses: [] properties: - name: githits:record_kind value: locked_package - name: githits:lockfile_path value: two/package-lock.json - name: githits:license_artifact_verification value: not_checked publisher_evidence: capture_status: present controlling_index: 0 coverage: complete display_value: MIT expression: MIT observations: - interpretation: expression: MIT interpretation_methods: - spdx_expression issues: [] status: expression syntax: spdx observation: field: license relation: single scope: release source: npm_registry statements: - MIT status: present version: 1.0.0 relationship: controlling reason: publisher_release_metadata status: expression purl: pkg:npm/dependency@1.0.0 record_kind: locked_package scope: excluded source_evidence: null type: library version: 1.0.0 - bom_ref: go external_references: [] hashes: [] licenses: [] name: example.com/source observed_licenses: - license: name: Apache-2.0 - license: name: MIT properties: - name: githits:record_kind value: resolved_package - name: githits:manifest_path value: go.mod publisher_evidence: null purl: pkg:golang/example.com/source@v1.0.0 record_kind: resolved_package scope: null source_evidence: checked_at: '2026-10-22T12:00:00Z' files: - detected_licenses: - Apache-2.0 path: LICENSE - detected_licenses: - MIT path: nested/LICENSE last_attempt_at: '2026-10-22T12:00:00Z' last_attempt_status: ambiguous method: licensecheck module: example.com/source provider: pkg_go_dev status: ambiguous url: >- https://pkg.go.dev/example.com/source@v1.0.0?tab=licenses version: v1.0.0 type: library version: v1.0.0 - bom_ref: file external_references: [] hashes: [] licenses: [] name: local subject observed_licenses: [] properties: [] publisher_evidence: null purl: null record_kind: null scope: null source_evidence: null type: file version: null inventory: completeness: recorded_lockfile_inventory compositions: - aggregate: unknown assemblies: - root - a - b - go - file dependencies: - dependsOn: - a ref: root - dependsOn: - b ref: a properties: - name: githits:completeness value: recorded_lockfile_inventory - name: githits:notice value: License metadata and connectivity may be incomplete. - name: githits:resolutions value: '[{"path":"package.json","status":"partial"}]' schema_version: 1 schema: $ref: '#/components/schemas/DependencyLicensesReport' description: >- JSON license report, at most 16,777,216 bytes. Read inventory coverage and component evidence together; a successful response may be partial and does not provide a pass/fail decision. 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: examples: invalid_session_id: value: code: INVALID_SESSION_ID detail: >- X-GitHits-Session-ID must occur once and match [A-Za-z0-9_-]{1,64}. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Invalid session ID type: about:blank upstream_validation: summary: Invalid request without a field-specific explanation value: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank validation: value: code: VALIDATION_ERROR detail: >- query: contains unknown parameters; use only the documented parameters. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- VALIDATION_ERROR, INVALID_SESSION_ID. Correct the field named in detail or the session header. These operations accept no query parameters. INVALID_SESSION_ID: a supplied session header is invalid or duplicated. VALIDATION_ERROR details identify the first invalid field and a reason when available. Array indices are zero-based; submitted values and unknown keys are not echoed. 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. Supply a valid Bearer credential. headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: description: Bearer challenge. schema: 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, ACCOUNT_INACTIVE, TERMS_ACCEPTANCE_REQUIRED. Check credential access, account eligibility and required terms; follow terms_url or acceptance_url when provided. 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 '404': content: application/problem+json: example: code: ANALYSIS_NOT_FOUND detail: The analysis is unavailable. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Analysis request failed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- ANALYSIS_NOT_FOUND. Check the submission id and credential. Missing, expired and inaccessible jobs have the same response. 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: GET, HEAD.' 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 '409': content: application/problem+json: example: code: ANALYSIS_PENDING detail: The analysis has not finished. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 409 title: Analysis request failed type: about:blank schema: oneOf: - allOf: - $ref: '#/components/schemas/ProblemResponse' - properties: code: enum: - ANALYSIS_PENDING type: string detail: enum: - The analysis has not finished. type: string title: enum: - Analysis request failed type: string required: - code - title - detail type: object - allOf: - $ref: '#/components/schemas/ProblemResponse' - properties: code: enum: - ANALYSIS_FAILED type: string detail: enum: - The analysis failed. type: string failure_code: description: >- Failure code from the analysis; new codes can appear. Internal diagnostics are not included. type: string title: enum: - Analysis request failed type: string required: - code - title - detail - failure_code type: object - allOf: - $ref: '#/components/schemas/ProblemResponse' - properties: code: enum: - INCOMPATIBLE_ANALYSIS type: string type: object description: >- ANALYSIS_PENDING, ANALYSIS_FAILED, INCOMPATIBLE_ANALYSIS. For ANALYSIS_PENDING, wait through status/events and retry this GET. For ANALYSIS_FAILED, inspect failure_code before submitting new work. For INCOMPATIBLE_ANALYSIS, use a job created with kind=sbom&format=cyclonedx. 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 '422': content: application/problem+json: example: code: LICENSE_REPORT_TOO_LARGE detail: The licenses report exceeds the response limit. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: Licenses request failed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- LICENSE_REPORT_TOO_LARGE. The JSON report is too large. Use the job's result_url to download its original CycloneDX document, or submit a smaller analysis if appropriate. 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 '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. Respect Retry-After when supplied before trying again. RATE_LIMITED can also mean your shared daily allowance is exhausted. When Retry-After is supplied, wait until that delay or HTTP date before trying again. headers: Cache-Control: schema: enum: - no-store type: string Retry-After: description: >- Delay in seconds or an HTTP date indicating when to retry, when supplied. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '500': description: >- A request ID could not be assigned. The response has an empty body and no X-Request-ID or problem object; try again later. 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. The analysis result could not be read. Keep X-Request-ID for support and report a persistent failure; a new submission creates another analysis. 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 '503': content: application/problem+json: example: code: ANALYSIS_UNAVAILABLE detail: Analysis is temporarily unavailable. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 503 title: Analysis request failed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- ANALYSIS_UNAVAILABLE, UPSTREAM_UNAVAILABLE. Retry reading the same job later; this does not start another analysis. QUOTA_UNAVAILABLE: your daily allowance could not be checked. This is temporary; retry the same request later (retryable=true). 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: >- TIMEOUT. Retry reading the same job later; this does not start another analysis. 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: DependencyLicensesReport: additionalProperties: true description: >- JSON license inventory with separate license choices, publisher statements and source-file observations, plus input attribution and coverage. It provides evidence for your own evaluation rather than an allow/deny result. Additional fields can appear. properties: components: description: >- All reported occurrences in their original order, with the selected primary project/source entry first when one exists. Keep repeated names, versions and package URLs separate; use bom_ref and input-path properties for attribution. items: $ref: '#/components/schemas/DependencyLicensesComponent' type: array inventory: $ref: '#/components/schemas/DependencyLicensesInventory' schema_version: description: Version of this JSON report structure, currently 1. enum: - 1 type: integer required: - schema_version - inventory - components type: object ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: Link for accepting the required terms, when provided. type: string code: description: The stable uppercase API error code. type: string detail: description: >- Human-readable explanation. Wording can change; use code and structured fields for program logic. Validation errors identify the first invalid field (including zero-based array indices) and a reason; version errors can include canonical-version guidance. type: string instance: description: >- Request ID matching the X-Request-ID response header; include it when seeking support. type: string retryable: description: >- Whether retrying later may help, when supplied. Follow this flag for lookup/provider outcomes and temporary daily-allowance failures; malformed evidence can be nonretryable. type: boolean status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: Link to the terms that require acceptance, when provided. 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 DependencyLicensesComponent: additionalProperties: true description: >- One reported project, package, source or file entry. A package can appear more than once, for example in different lockfiles; keep those occurrences separate even when name, version or package URL match. properties: bom_ref: description: >- Opaque reference for this occurrence, used by inventory relationships. null means no reference was available. Do not merge entries by name, version or package URL. type: - string - 'null' external_references: description: >- Source or distribution locations with their declared provenance. A reference may have its own hashes; keep those on that reference rather than moving them to component hashes. The presence of a URL does not prove an installed copy was downloaded or verified. items: additionalProperties: true type: object type: array hashes: description: >- Checksums recorded for this component or file. They are not recalculated by the report. Keep them separate from hashes on external_references; neither collection proves that your installed copy matches. items: additionalProperties: true type: object type: array licenses: description: >- Reported license-choice objects, usually containing expression (for example MIT OR Apache-2.0) or license with an id/name, and optional acknowledgement. Keep each choice intact. Separate entries do not imply AND or OR, and an empty array means no choices were reported. These are evidence, not a pass/fail decision. items: additionalProperties: true type: object type: array name: description: >- Reported project, package, source or file name. A name alone does not identify a unique package occurrence. type: string observed_licenses: description: >- Independent license observations, such as licenses identified in source files. Keep these separate from licenses and publisher statements; see source_evidence for file paths and detection status. An empty array means no observations were reported, not that every file was checked. items: additionalProperties: true type: object type: array properties: description: >- Additional input/source attribution and metadata as name/value pairs. Match entries by name, retain repetitions and allow unfamiliar names; value can be absent. Paths and status values are plain strings. Known values such as githits:manifest_paths, githits:lockfile_paths and githits:license_raw_statements contain JSON encoded inside a string and need a separate parse if you use them. Publisher/source evidence is already available as objects in publisher_evidence and source_evidence. items: $ref: '#/components/schemas/SbomProperty' type: array publisher_evidence: additionalProperties: true description: >- Original publisher license statements and the context needed to interpret them. This is already a JSON object. observations retains statement text, source, scope, field, version, interpretation/issues and relationship. capture_status describes retained statement capture; coverage concerns that statement collection, not your dependency inventory. status/reason/expression describe interpretation. controlling_index identifies the selected observation when one was selected. Package/repository context may not apply to a specific release. null means no publisher evidence object was available, not that the package has no license. Accept unfamiliar statuses and additional fields. type: - object - 'null' purl: description: >- Package URL (PURL), or null when unavailable. Its presence identifies a package coordinate; it does not verify your installed artifact. type: - string - 'null' record_kind: description: >- Why this entry is included: examples are manifest for an uploaded project, resolved_package for a dependency found by resolution, and locked_package for a lockfile occurrence. null means unspecified. Other values can appear. type: - string - 'null' scope: description: >- Reported component scope, for example excluded. null means the scope was not specified. Entries with excluded scope remain in the report. type: - string - 'null' source_evidence: additionalProperties: true description: >- Source-file license detection details, already a JSON object. provider/method identify the detection service and technique; module/version identify what was examined. files contains path and detected_licenses, including nested license files. checked_at/status describe the available observation; last_attempt_at/last_attempt_status describe the latest attempt, which can fail while an older observation remains. null means no source observation was available. Accept unfamiliar statuses and additional fields; this does not certify an installed artifact. type: - object - 'null' type: description: >- Component classification, for example library or file. Additional string values can appear; accept unfamiliar classifications. type: string version: description: Reported version text, or null when no version was available. type: - string - 'null' required: - bom_ref - name - version - purl - type - scope - record_kind - licenses - observed_licenses - publisher_evidence - source_evidence - external_references - hashes - properties type: object DependencyLicensesInventory: additionalProperties: true description: >- Input provenance, inventory coverage and reported dependency relationships. Read these facts alongside the component list; successful analysis can still be partial. properties: completeness: description: >- How the inventory was built, for example recorded_lockfile_inventory, resolved_manifest_inventory, partial_manifest_inventory or mixed_dependency_inventory. null means unreported, and additional values can appear. This does not measure license coverage; HTTP 200 or a component count does not prove completeness. type: - string - 'null' compositions: description: >- Coverage declarations for groups of component references, with standard CycloneDX keys such as aggregate and assemblies. They describe inventory/connectivity coverage, not how many licenses are known. Allow unfamiliar fields and aggregate values. items: additionalProperties: true type: object type: array dependencies: description: >- Reported dependency relationships, using standard keys such as ref and dependsOn to refer to component bom_ref values. Missing edges or an empty array do not by themselves prove a complete graph or a dependency-free package; read coverage and notices too. items: additionalProperties: true type: object type: array properties: description: >- Additional facts about uploaded inputs, resolution results and coverage, as name/value pairs. Values for githits:resolutions, githits:declarations, githits:lockfiles, githits:manifest_associations, githits:dependency_coverage, githits:relationships, githits:primary_subject and githits:declaration_agreement contain JSON encoded inside strings: parse those separately when needed. Dependency coverage is reported in githits:dependency_coverage and inventory.compositions. Some values, such as githits:notice and githits:completeness, are plain strings; parse only names you know to contain JSON. Match by name, keep repetitions and allow unfamiliar properties; value can be absent. items: $ref: '#/components/schemas/SbomProperty' type: array required: - completeness - properties - compositions - dependencies type: object SbomProperty: additionalProperties: true description: >- Extensible standard property. Match by name rather than array position; ignore names your client does not recognize. examples: - name: githits:record_kind value: resolved_package - name: githits:manifest_paths value: '["app/package.json"]' properties: name: description: >- Property name. GitHits evidence uses the githits: namespace; other namespaces are also allowed. type: string value: description: >- Optional evidence value, encoded as a string when present. Structured values such as githits:declarations, githits:resolutions, githits:lockfiles, githits:manifest_associations, githits:manifest_paths and githits:lockfile_paths contain JSON; parse those separately when needed. Do not JSON-parse every property: paths and statuses can be plain strings. type: string required: - name type: object securitySchemes: bearer_auth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.