> ## 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 or kind=audit 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 for sbom or json for audit. SBOM accepts cyclonedx/spdx/text; audit accepts only json. Crossed effective pairs are rejected before upstream admission. Audit additionally accepts report_version=2 or 3 as query or multipart text, with multipart precedence. Omission preserves v2; non-audit use and invalid/repeated controls are rejected before admission. Inspect returned schema_version, since an older worker may return v2 even when 3 was requested. Repeated values within one location and unknown query or multipart fields are rejected. The gateway reports one provisional operation. One monthly analysis unit is reserved at admission for an SBOM or audit job, charged on success, and released if the analysis fails. See POST /v1/experimental/sbom for input support, strict whole-upload rejection and shared submission limits. Reads, progress, reconnects and execution retries consume zero additional analysis 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 |

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

    | Compare dependency snapshots | Submit an explicit base/head pair, follow
    shared analysis status/SSE, then download source-local changes and
    independent analysis coverage |

    | 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 `<token>` with your GitHits token. Send the token in
    `Authorization: Bearer <token>`. 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/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 or
        kind=audit 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 for sbom
        or json for audit. SBOM accepts cyclonedx/spdx/text; audit accepts only
        json. Crossed effective pairs are rejected before upstream admission.
        Audit additionally accepts report_version=2 or 3 as query or multipart
        text, with multipart precedence. Omission preserves v2; non-audit use
        and invalid/repeated controls are rejected before admission. Inspect
        returned schema_version, since an older worker may return v2 even when 3
        was requested. Repeated values within one location and unknown query or
        multipart fields are rejected. The gateway reports one provisional
        operation. One monthly analysis unit is reserved at admission for an
        SBOM or audit job, charged on success, and released if the analysis
        fails. See POST /v1/experimental/sbom for input support, strict
        whole-upload rejection and shared submission limits. Reads, progress,
        reconnects and execution retries consume zero additional analysis 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 or audit 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:
            $ref: '#/components/schemas/LockfileJobKind'
        - description: >-
            Requested result format. A multipart format field overrides this
            value. Omit both locations to select cyclonedx for sbom or json for
            audit. Only sbom with cyclonedx/spdx/text and audit with json are
            admitted. 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/LockfileJobOutputFormat'
        - description: >-
            Audit only: opt into native lifecycle with 3. Omission or 2
            preserves v2. Multipart text overrides this query value; duplicates
            and unsupported values are rejected. Dispatch on the returned
            schema_version, including a possible v2 response to a v3 request.
          in: query
          name: report_version
          required: false
          schema:
            enum:
              - '2'
              - '3'
            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
      requestBody:
        content:
          multipart/form-data:
            encoding:
              files[]:
                contentType: application/octet-stream
              format:
                contentType: text/plain
              kind:
                contentType: text/plain
              report_version:
                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/LockfileJobOutputFormat'
                  description: >-
                    Optional result format. SBOM accepts cyclonedx, spdx, or
                    text and defaults to cyclonedx; audit accepts json and
                    defaults to json. This multipart value overrides the query
                    parameter. Crossed kind and format pairs are rejected.
                    Duplicate values in one location are rejected.
                kind:
                  $ref: '#/components/schemas/LockfileJobKind'
                  description: >-
                    Required across the query and multipart body; accepted
                    values are sbom and audit. When both locations supply kind,
                    this multipart value wins. Duplicate values in this location
                    are rejected.
                report_version:
                  description: >-
                    Audit jobs only. Select native lifecycle report 3
                    explicitly; omission or 2 preserves released v2. Body
                    overrides the query. Duplicate values in one location and
                    non-audit use are rejected.
                  enum:
                    - '2'
                    - '3'
                  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 a
          required kind of sbom or audit either as a query parameter or the
          multipart kind field; if both locations supply kind, the body field
          wins. SBOM jobs accept cyclonedx, spdx, or text and default to
          cyclonedx; audit jobs accept json and default to json. Crossed
          kind/format pairs are rejected. 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. Audit
          alone accepts optional report_version=2 or 3 in query or multipart
          text; the body wins. Omission preserves v2. Clients inspect returned
          schema_version; older workers can return v2 even when v3 was
          requested.
        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
                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: 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
          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


            QUOTA_EXCEEDED means a usage allowance is exhausted. When supplied,
            pool identifies the allowance (analysis for monthly analysis or
            requests for daily requests), limit gives its size, and resets_at
            gives its RFC 3339 reset time. 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: 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: >-
            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
          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 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
          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:
    LockfileJobKind:
      description: Supported request job kinds; response vocabulary remains open.
      enum:
        - sbom
        - audit
      type: string
    LockfileJobOutputFormat:
      description: >-
        Closed request formats. SBOM accepts cyclonedx/spdx/text; audit accepts
        only json. Omission chooses the kind-specific default.
      enum:
        - cyclonedx
        - spdx
        - text
        - json
      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. Open
            response vocabulary; clients must accept unfamiliar values and
            codes.
          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: >-
            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
        limit:
          description: >-
            Allowance in the exhausted pool's units for `QUOTA_EXCEEDED` when
            supplied.
          format: int64
          minimum: 0
          type: integer
        pool:
          description: >-
            Exhausted allowance pool for `QUOTA_EXCEEDED` when supplied. Known
            values include `analysis` and `requests`. Clients must accept new
            values.
          type: string
        resets_at:
          description: >-
            Time when the exhausted allowance resets for `QUOTA_EXCEEDED` when
            supplied.
          format: date-time
          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
    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. Response values can evolve:
        accept values you do not recognise. A value the API does not yet
        recognise is returned as unknown. Known values include: unknown,
        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.