> ## 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. # Submit a lockfile analysis job > Submit uploaded manifests and lockfiles for asynchronous dependency analysis. Authenticate with a GitHits Bearer credential for an active account that has accepted the required terms. Supply kind=sbom either as a query parameter or multipart field; when both are supplied, the multipart field wins. Supply format in either location or both; the multipart field wins, and omission selects cyclonedx. Repeated values within one location and unknown query or multipart fields are rejected. The gateway reports a provisional cost of one unit for submission; backend job admission currently charges 100 daily units. This endpoint returns HTTP 202 when the job is queued. The existing /v1/experimental/sbom endpoint remains synchronous and returns an HTTP 200 document. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/experimental/lockfile-jobs 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 | | Generate an SBOM | Upload manifests and lockfiles to receive a CycloneDX, SPDX or text inventory | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Standard SBOM documents 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. 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: >- 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/lockfile-jobs: post: tags: - Experimental summary: Submit a lockfile analysis job description: >- Submit uploaded manifests and lockfiles for asynchronous dependency analysis. Authenticate with a GitHits Bearer credential for an active account that has accepted the required terms. Supply kind=sbom either as a query parameter or multipart field; when both are supplied, the multipart field wins. Supply format in either location or both; the multipart field wins, and omission selects cyclonedx. Repeated values within one location and unknown query or multipart fields are rejected. The gateway reports a provisional cost of one unit for submission; backend job admission currently charges 100 daily units. This endpoint returns HTTP 202 when the job is queued. The existing /v1/experimental/sbom endpoint remains synchronous and returns an HTTP 200 document. operationId: submit_lockfile_job parameters: - description: >- Job kind. Provide sbom in this query parameter or the multipart body; at least one location is required. If both locations provide it, the body wins. Repeated values in this location are rejected. in: query name: kind required: false schema: enum: - sbom type: string - description: >- Requested result format. A multipart format field overrides this value. Omit both locations to select cyclonedx. Repeated values in one location are rejected; unknown query fields are rejected. Accept does not select the result format. in: query name: format required: false schema: $ref: '#/components/schemas/SbomOutputFormat' - 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 requestBody: content: multipart/form-data: encoding: files[]: contentType: application/octet-stream format: contentType: text/plain kind: contentType: text/plain schema: additionalProperties: false properties: files[]: description: >- Repeat the literal field name files[] once per file, with raw UTF-8 file contents rather than base64. Set each part's filename to its path relative to a common repository root, for example app/package.json and app/package-lock.json. Preserve directory structure so manifests can be associated with their lockfiles. Send 1–256 files, each at most 5,242,880 bytes. Each filename must be at most 1,024 UTF-8 bytes and must be relative, with no empty, dot (.) or parent (..) path segments, backslashes or control characters. Upload manifests and/or lockfiles supported by the GitHits inventory service; their contents are analyzed asynchronously. items: format: binary type: string maxItems: 256 minItems: 1 type: array format: $ref: '#/components/schemas/SbomOutputFormat' description: >- Optional result format. This multipart value overrides the query parameter. Omit both to receive CycloneDX JSON; duplicate values in one location are rejected. kind: description: >- Optional multipart job kind. At least one sbom value is required across this field and the query parameter; when both are present, this multipart value wins. Duplicate values in this location are rejected. enum: - sbom type: string required: - files[] type: object description: >- Send multipart/form-data. The complete request, including multipart headers and boundaries, must fit within 8,000,000 bytes. Supply kind=sbom either as a query parameter or the multipart kind field; if both locations supply it, the body field wins. The selected format also accepts query or body values, with the body winning when both are present. Repeated values within one location and unknown fields are rejected. required: true responses: '202': content: application/json: example: events_url: >- /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/events expires_at: '2026-10-10T12:00:00Z' id: 01900000-0000-7000-8000-000000000001 result_url: >- /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/result state: queued status_url: >- /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001 schema: $ref: '#/components/schemas/LockfileJobAccepted' description: The upload was admitted and queued for asynchronous analysis. headers: Cache-Control: schema: enum: - no-store type: string Location: description: Canonical relative URL for the job status resource. schema: format: uri-reference pattern: >- ^/v1/experimental/lockfile-jobs/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$ 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 validation: value: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- VALIDATION_ERROR INVALID_SESSION_ID: a supplied session header is invalid or duplicated. 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 headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: description: Bearer authentication 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 headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '405': content: application/problem+json: example: code: METHOD_NOT_ALLOWED detail: The requested method is not supported for this route. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 405 title: Method not allowed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: 'METHOD_NOT_ALLOWED: the route does not support this HTTP method.' headers: Allow: description: 'Supported methods: POST.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '408': content: application/problem+json: example: code: UPLOAD_TIMEOUT detail: The upload did not complete in time. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 408 title: Upload timed out type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: UPLOAD_TIMEOUT headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '413': content: application/problem+json: example: code: INPUT_TOO_LARGE detail: The upload exceeds a file, path, count or body limit. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 413 title: Input too large type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: INPUT_TOO_LARGE 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 '415': content: application/problem+json: example: code: UNSUPPORTED_MEDIA_TYPE detail: Use multipart/form-data. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 415 title: Unsupported media type type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: UNSUPPORTED_MEDIA_TYPE 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: NO_MANIFEST_EVIDENCE detail: >- Supply a manifest with named package evidence or a supported lockfile. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: SBOM request failed type: about:blank schema: oneOf: - allOf: - $ref: '#/components/schemas/ProblemResponse' - properties: code: enum: - NO_MANIFEST_EVIDENCE - UNREPRESENTABLE_SPDX - SBOM_OUTPUT_TOO_LARGE type: string type: object - $ref: '#/components/schemas/SbomProblem' description: >- NO_MANIFEST_EVIDENCE, UNREPRESENTABLE_SPDX, SBOM_OUTPUT_TOO_LARGE, UNUSABLE_MANIFEST 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 headers: Cache-Control: schema: enum: - no-store type: string Retry-After: description: Validated delay or HTTP-date for quota reset, when available. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '500': description: >- Request identity could not be created. Empty body without X-Request-ID; no problem object is available. headers: Cache-Control: schema: enum: - no-store type: string x-githits-empty-identity-failure: true '502': content: application/problem+json: example: code: UPSTREAM_ERROR detail: The upstream service failed to provide a response. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: UPSTREAM_ERROR 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 unavailable type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: ANALYSIS_UNAVAILABLE, UPSTREAM_UNAVAILABLE 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 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: SbomOutputFormat: default: cyclonedx description: >- cyclonedx returns CycloneDX 1.7 JSON (application/vnd.cyclonedx+json); spdx returns SPDX 2.3 tag-value (text/spdx); text returns a human-readable report (text/plain). All outputs use UTF-8. Accept does not select the successful output format. enum: - cyclonedx - spdx - text type: string LockfileJobAccepted: additionalProperties: false example: events_url: >- /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/events expires_at: '2026-10-10T12:00:00Z' id: 01900000-0000-7000-8000-000000000001 result_url: >- /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/result state: queued status_url: /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001 properties: events_url: description: Canonical relative URL for the job's server-sent event stream. example: >- /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/events format: uri-reference pattern: >- ^/v1/experimental/lockfile-jobs/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/events$ type: string expires_at: description: Time after which the job and its result are no longer available. example: '2026-10-10T12:00:00Z' format: date-time type: string id: description: Opaque identifier for this analysis job. example: 01900000-0000-7000-8000-000000000001 format: uuid pattern: >- ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$ type: string result_url: description: >- Canonical relative URL for retrieving the completed analysis document. example: >- /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001/result format: uri-reference pattern: >- ^/v1/experimental/lockfile-jobs/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/result$ type: string state: description: Initial state when the accepted job is placed in the queue. enum: - queued example: queued type: string status_url: description: Canonical relative URL for the job status snapshot. example: /v1/experimental/lockfile-jobs/01900000-0000-7000-8000-000000000001 format: uri-reference pattern: >- ^/v1/experimental/lockfile-jobs/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$ type: string required: - id - state - expires_at - status_url - events_url - result_url 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: A stable, client-safe explanation of the failure. type: string instance: description: The active request trace ID. type: string status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: 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 SbomProblem: allOf: - $ref: '#/components/schemas/ProblemResponse' - properties: files: description: >- Unusable uploaded files; paths refer only to this request's uploads. items: $ref: '#/components/schemas/SbomFileFailure' maxItems: 256 minItems: 1 type: array required: - files type: object description: >- File-specific diagnostics returned only when generation rejects uploaded inputs. SbomFileFailure: description: One rejected uploaded file, without parser diagnostics. properties: path: description: Original repository-relative filename supplied by the caller. type: string status: $ref: '#/components/schemas/SbomFileStatus' description: Why this file could not contribute evidence. required: - path - status type: object SbomFileStatus: description: Processing outcome for each uploaded file. enum: - unsupported - invalid_utf8 - unparsed type: string securitySchemes: bearer_auth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.