> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import a foreign SBOM document as a partial-coverage scan

> Accepts a CycloneDX or SPDX 2.3 JSON document describing a project's declared components. The format is detected from the document's content (`bomFormat` vs `spdxVersion`), never from the filename or the client's Content-Type — the upload is untrusted input. Tag-value SPDX is not accepted; JSON only. Unlike `POST /v1/scans`, no source code is scanned — the resulting scan always carries `source_type: sbom` and `coverage: partial`: an imported document is a snapshot of declared components, not a full-codebase scan, so it never marks a prior full-coverage scan's findings absent.

A component with a `purl` is enriched (vulnerabilities/licenses) exactly like a code-matched dependency. A component with a name but no `purl` is still imported — it simply carries no enrichments, since there is no identity to look one up by.

The import pipeline (parse → emit findings → enrich) runs in the background. Clients poll `GET .../scans/{id}` for progress, same as any other scan.

Re-importing the exact same document (same `project_id` + content hash) reuses the existing Scan Intent rather than creating a duplicate scan.

The `scanners` field is not accepted because an SBOM import does not run source-code scanner phases; if present, the request is rejected with 400.



## OpenAPI

````yaml /api-reference/earnie/scans-openapi.json post /v1/scans:import-sbom
openapi: 3.0.3
info:
  title: Earnie Scans API
  description: >-
    Submit scans, follow their progress, and read their results: files, matches,
    cryptography, AI models, and posture.
  version: 1.0.0
servers:
  - url: https://{tenant}.earnie.dev
    description: Your Earnie deployment
    variables:
      tenant:
        default: your-company
        description: >-
          Your organization's Earnie address, as shown in your browser when you
          sign in.
security:
  - bearerAuth: []
paths:
  /v1/scans:import-sbom:
    post:
      tags:
        - scans
      summary: Import a foreign SBOM document as a partial-coverage scan
      description: >-
        Accepts a CycloneDX or SPDX 2.3 JSON document describing a project's
        declared components. The format is detected from the document's content
        (`bomFormat` vs `spdxVersion`), never from the filename or the client's
        Content-Type — the upload is untrusted input. Tag-value SPDX is not
        accepted; JSON only. Unlike `POST /v1/scans`, no source code is scanned
        — the resulting scan always carries `source_type: sbom` and `coverage:
        partial`: an imported document is a snapshot of declared components, not
        a full-codebase scan, so it never marks a prior full-coverage scan's
        findings absent.


        A component with a `purl` is enriched (vulnerabilities/licenses) exactly
        like a code-matched dependency. A component with a name but no `purl` is
        still imported — it simply carries no enrichments, since there is no
        identity to look one up by.


        The import pipeline (parse → emit findings → enrich) runs in the
        background. Clients poll `GET .../scans/{id}` for progress, same as any
        other scan.


        Re-importing the exact same document (same `project_id` + content hash)
        reuses the existing Scan Intent rather than creating a duplicate scan.


        The `scanners` field is not accepted because an SBOM import does not run
        source-code scanner phases; if present, the request is rejected with
        400.
      operationId: PostV1ScansImportSbom
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - project_id
              properties:
                file:
                  type: string
                  format: binary
                  description: The CycloneDX or SPDX JSON document (max 32 MB).
                project_id:
                  type: string
                  format: uuid
                  description: Required link to the owning project.
                name:
                  type: string
                  description: Optional display name. Defaults to the document filename.
                enrichments:
                  type: array
                  items:
                    $ref: '#/components/schemas/EnrichmentKey'
                  description: >-
                    Canonical optional PURL enrichment list — same encoding as
                    `POST /v1/scans`. Omitted defaults to
                    ["vulnerabilities","licenses"]; an imported document has no
                    source files, so snippet classification does not run by
                    default. An explicit empty value runs no optional
                    enrichments.
      responses:
        '200':
          description: An equivalent import reused an existing Scan Intent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
        '202':
          description: >-
            Import accepted. The pipeline runs in the background; poll GET to
            track progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
        '400':
          description: >-
            Missing `file` part, malformed multipart request, or a `scanners`
            field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Missing `scans:write` permission, API key scanner restriction, or
            enabled scanner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `sbom_already_imported` — the project already has a scan that
            imported this exact document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Document exceeds the configured size cap (32 MB).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |-
            Validation failure. Possible codes:
             * `project_not_found`
             * `project_archived`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    EnrichmentKey:
      type: string
      enum:
        - vulnerabilities
        - licenses
        - snippet_classification
      description: >-
        Identifiers for optional PURL-driven enrichments. `matching` is the
        always-on core engine and is not an enrichment key. Dependency inventory
        is produced by the always-on dependency stage. Omitting `enrichments`
        defaults to ["vulnerabilities","licenses","snippet_classification"].
        `snippet_classification` scores each open-source snippet match and
        proposes the ones that look like false positives. It needs the OSS
        scanner and is skipped for a scan without one.
    Scan:
      type: object
      required:
        - id
        - project_id
        - project
        - name
        - status
        - archive_filename
        - archive_sha256
        - archive_size_bytes
        - source_ref
        - files_total
        - files_scanned
        - matches_total
        - crypto_observations_available
        - created_by
        - created_at
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
          description: >-
            The owning project. Every scan belongs to exactly one project.
            `project` carries the denormalised reference.
        project:
          $ref: '#/components/schemas/ProjectRef'
        name:
          type: string
          description: Defaults to the uploaded archive's filename.
        status:
          $ref: '#/components/schemas/ScanStatus'
        intent_hash:
          type: string
          nullable: true
          description: Server-computed Scan Intent identity; clients never supply it.
        reused:
          type: boolean
          description: True when this submission trigger reused an existing eligible scan.
        rerun_of:
          type: string
          format: uuid
          nullable: true
          description: The prior scan explicitly superseded by this rerun, when applicable.
        cancellation_reason:
          allOf:
            - $ref: '#/components/schemas/ScanCancellationReason'
          nullable: true
        superseded_by_scan_id:
          type: string
          format: uuid
          nullable: true
          description: Replacement scan that superseded this cancelled scan.
        triggers:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ScanTrigger'
          description: Append-only submission triggers associated with this scan.
        error_code:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
        archive_filename:
          type: string
        archive_sha256:
          type: string
        archive_size_bytes:
          type: integer
          format: int64
        source_ref:
          type: string
          description: >-
            SourceStorage opaque key for the retained keep-set archive. While
            `status` is `receiving`, this MAY be the placeholder `pending`.
        source_type:
          $ref: '#/components/schemas/ScanSourceType'
        repo_full_name:
          type: string
          nullable: true
          description: Git provenance (git-sync GS-5) — set on git-sourced scans.
        git_ref:
          type: string
          nullable: true
          description: >-
            The ref that was requested (branch/tag); null when the default
            branch was used implicitly.
        commit_sha:
          type: string
          nullable: true
          description: The commit the archive was fetched at (resolved before download).
        result_ref:
          type: string
          nullable: true
          description: SourceStorage opaque key for result.json (set on completion).
        files_total:
          type: integer
          description: Populated after extraction.
        files_scanned:
          type: integer
          description: Updated during the scanning phase.
        matches_total:
          type: integer
          description: Count of rows in scans.file_components for this scan.
        crypto_observations_available:
          type: boolean
          description: >-
            True when this scan has an immutable crypto observation marker.
            Clients use this authoritative flag to decide whether a crypto diff
            can be requested; posture history is a derived projection.
        crypto_diff_baseline:
          allOf:
            - $ref: '#/components/schemas/CryptoDiffBaseline'
          nullable: true
          description: >-
            The nearest earlier completed scan with full coverage and a full
            immutable crypto observation, when this scan is also eligible.
            Ineligible intervening scans are skipped. Present on scan detail
            responses only. Null means no valid crypto comparison exists.
        scanner_version:
          type: string
          nullable: true
        scanner_api_url:
          type: string
          nullable: true
        scanner_session_id:
          type: string
          format: uuid
          nullable: true
        created_by:
          allOf:
            - $ref: '#/components/schemas/ScanActor'
          description: Who submitted this scan.
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        enrichments:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/EnrichmentKey'
          description: >-
            The canonical resolved PURL enrichment list. Null only for scans
            created before optional enrichments were persisted.
        stages:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ScanStageProgress'
          description: >-
            Staged progress for each enrichment phase. Null when no stage rows
            exist yet (scan still in core matching phase). Non-null once the
            first stage row has been written. Populated by the enrichment-stage
            framework.
        added_count:
          type: integer
          nullable: true
          description: >-
            Number of findings added in this reconciliation run (APP-5 S3.1).
            Zero is distinct from null — zero means reconciliation ran and found
            no new additions.
        persisted_count:
          type: integer
          nullable: true
          description: >-
            Number of prior findings that were reaffirmed in this scan (APP-5
            S3.1).
        absent_count:
          type: integer
          nullable: true
          description: >-
            Number of previously present findings marked absent by this scan
            (APP-5 S3.1).
        coverage:
          allOf:
            - $ref: '#/components/schemas/ScanCoverage'
          nullable: true
          description: >-
            Whether this scan covered the entire codebase (full) or only a
            partial slice such as a PR diff or agent working set (partial).
        result_scope:
          type: string
          enum:
            - project
            - scan
            - model
          description: >-
            Who owns this scan's results. `project`: its findings, files and
            verdicts are the project's. `scan`: they belong to this scan alone,
            as every pull request scan's do; project posture does not change
            until the code reaches the default branch, and a finding the pull
            request introduced cannot be triaged yet. `model`: the scan of an
            uploaded Model; its findings are the project's, but the scan never
            stands for the project. Absent on a scan created before the field
            existed; read that as `project`.
        scan_context:
          allOf:
            - $ref: '#/components/schemas/ScanContext'
          nullable: true
          description: >-
            The submission provenance persisted with this scan, with `producer`
            and `coverage` as the server resolved them.
        effective:
          allOf:
            - $ref: '#/components/schemas/ScanEffectiveConfig'
          nullable: true
          description: >-
            What the server actually resolved at submit time — scanners,
            enrichments, coverage and the policy snapshot.
        narrowed_from_request:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ScanNarrowing'
          description: >-
            The adjustable fields the server resolved to something narrower than
            the request asked for.
        gate:
          allOf:
            - $ref: '#/components/schemas/ScanGate'
          nullable: true
          description: >-
            What this scan's policies decided, collapsed by precedence. Derived
            at read time from the evaluations this scan is anchored to plus the
            *current* Policy Approval overlay, so granting or revoking an
            approval moves the gate of the same scan while the recorded verdicts
            stay untouched.


            The scan's own lifecycle is decided first. A scan that has not
            completed reports `evaluation.status: pending` and a null gate,
            whatever its policies concluded midway — policies are evaluated
            before the scan is marked complete, so a scan can hold a full set of
            verdicts and then fail, and its gate is `error` rather than whatever
            those verdicts said.


            Null when no gate can be attributed to the scan: while it is still
            running, and for a completed scan with policies in its snapshot but
            no recorded evaluation — which is either a scan predating the
            per-scan evaluation link or one whose policies were all detached
            before evaluation ran. Null is neither `pass` nor `none`.


            `GET /v1/scans/{scanId}/policy-verdicts` explains a non-null value
            policy by policy.


            Distinct from `PostureGate`, which is a project's standing rollup
            and carries no `require` or `error` member.
        gate_reason:
          allOf:
            - $ref: '#/components/schemas/ScanGateReason'
          nullable: true
          description: Present exactly when `gate` is.
        evaluation:
          allOf:
            - $ref: '#/components/schemas/ScanPolicyEvaluation'
          nullable: true
          description: >-
            This scan's policy-evaluation state. Non-null whenever anything can
            be said about the evaluation — including while it is `pending`,
            where `gate` is null and this block is how a client learns an answer
            is still coming.


            Null only for a scan whose gate cannot be attributed at all: one
            created before the per-scan evaluation link existed, or one that
            completed with policies in its snapshot and no recorded evaluation.


            `policies_evaluated` and `evaluated_at` report what actually ran,
            whatever the status says about the gate — a scan that evaluated two
            policies and then failed did evaluate two policies, and `GET
            /v1/scans/{scanId}/policy-verdicts` lists them.
        codebase_divergence:
          allOf:
            - $ref: '#/components/schemas/CodebaseDivergence'
          nullable: true
          description: >-
            Read-time divergence result. Null for git-sourced scans and when the
            project has no prior inventory (first scan). Non-null only for
            upload scans that have been compared against an existing project
            inventory.
        publication:
          allOf:
            - $ref: '#/components/schemas/ScanPublicationBlock'
          nullable: true
          description: >-
            Whether the provider has heard this scan's verdict. A pull request
            scan submitted through a provider Connection places an `Earnie`
            check on its head SHA; this block is the outbox state of that
            placement. Publication state never changes a verdict: the gate above
            is what Earnie decided, this is whether GitHub was told.


            Absent for scans that publish nothing — uploads, CLI scans of a
            branch — and when no Connection is configured.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code. `source_not_available` when WFP upload
            lands).
        message:
          type: string
    ProjectRef:
      type: object
      description: Light reference to a linked project (denormalised for list rendering).
      required:
        - id
        - slug
        - name
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
    ScanStatus:
      type: string
      enum:
        - pending
        - receiving
        - extracting
        - scanning
        - importing
        - completed
        - failed
        - cancelled
      description: >-
        Lifecycle states:

        - `pending` — the scan exists; receiving its input has not started or
        finished

        - `receiving` — the scan's input is being transferred (files, a
        repository, or an archive)

        - `extracting` — an uploaded archive is being unpacked

        - `scanning` — the scanners are running

        - `importing` — an uploaded SBOM document is being read; SBOM imports
        skip `receiving` and `scanning`

        - `completed` — the scan finished and its results are available

        - `failed` — terminal failure; `error_code` and `error_message` are set

        - `cancelled` — terminal cancellation; no findings, gate result, or
        posture is published
    ScanCancellationReason:
      type: string
      enum:
        - superseded
        - user_requested
        - timeout
        - project_disconnected
        - change_request_closed
      description: Why a scan reached the terminal `cancelled` state.
    ScanTrigger:
      type: object
      required:
        - id
        - scan_id
        - outcome
        - producer
        - created_at
      properties:
        id:
          type: string
          format: uuid
        scan_id:
          type: string
          format: uuid
        outcome:
          $ref: '#/components/schemas/ScanTriggerOutcome'
        producer:
          $ref: '#/components/schemas/ScanProducer'
        created_at:
          type: string
          format: date-time
    ScanSourceType:
      type: string
      enum:
        - upload
        - git
        - sbom
        - model
      description: >-
        Where the scan's archive came from. `sbom` marks a scan created by
        importing a foreign SBOM document rather than scanning source code — it
        always carries `coverage: partial`. `model` marks the scan of an
        uploaded Model.
    CryptoDiffBaseline:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Human-readable name of the comparison scan.
    ScanActor:
      type: object
      description: >-
        The identity that submitted the scan. Replaces the former plain
        `created_by` user uuid: a scan may be submitted by an API key, a
        provider Connection or an internal worker, none of which is a user.
      required:
        - kind
        - id
      properties:
        kind:
          $ref: '#/components/schemas/ScanActorKind'
        id:
          type: string
          format: uuid
          description: >-
            The actor's row id — a user id, an API-key id, a Connection id or
            the internal job id, per `kind`. Not a foreign key to `users`.
    ScanStageProgress:
      type: object
      description: >-
        Progress for a single enrichment stage within a scan pipeline run. Rows
        are written by each Enricher phase; the UI polls `scan.stages[]` to
        render the staged-progress panel.
      required:
        - name
        - state
        - items_processed
        - items_total
      properties:
        name:
          type: string
          description: >-
            Stage key — matches the enrichment key or a core phase name (e.g.
            "receiving", "extracting", "matching"). For `receiving`, `items_*`
            are keep-set files (accepted vs planned).
        state:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
            - skipped
          description: Current lifecycle state of this stage.
        items_processed:
          type: integer
          description: >-
            Number of items processed so far. For `receiving`, count of keep-set
            files accepted into the cursor.
        items_total:
          type: integer
          description: >-
            Total items expected for this stage (0 when unknown). For
            `receiving`, count of keep-set files returned by the keep engine.
        started_at:
          type: string
          format: date-time
          nullable: true
          description: When the stage entered the running state; null until then.
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the stage reached a terminal state (completed/failed/skipped);
            null while running.
        warnings:
          type: array
          nullable: true
          items:
            type: string
          description: Non-fatal warning messages, populated on failed or degraded stages.
    ScanCoverage:
      type: string
      enum:
        - full
        - partial
      description: >-
        A scan's reach. `full` may add, reaffirm and mark-absent findings and so
        mutates canonical posture; `partial` only adds or updates what it
        touched. Coverage is a server rule: a client may downgrade to `partial`
        but never promote to `full`.
    ScanContext:
      type: object
      description: >-
        Optional provenance block accepted on every scan creation request.
        Persisted for the Audit Log, PR-feedback deep links and Scan Intent
        resolution. Every field except `producer` and `coverage` is informative
        to the client: the server stores it and never accepts it as a posture
        marker. A present `change_request` forces `partial` coverage;
        default-branch provenance is recorded only by server-owned paths after
        the branch head is resolved.
      properties:
        producer:
          $ref: '#/components/schemas/ScanProducer'
        coverage:
          allOf:
            - $ref: '#/components/schemas/ScanCoverage'
          description: >-
            The coverage the client intends. The server validates it: a
            downgrade to `partial` is honoured, a promotion to `full` is
            rejected with `coverage_promotion_rejected`.
        provider:
          allOf:
            - $ref: '#/components/schemas/ScanProvider'
          nullable: true
        repository:
          allOf:
            - $ref: '#/components/schemas/ScanRepositoryRef'
          nullable: true
        change_request:
          allOf:
            - $ref: '#/components/schemas/ScanChangeRequestRef'
          nullable: true
        commit_sha:
          type: string
          nullable: true
        branch:
          type: string
          nullable: true
        run:
          allOf:
            - $ref: '#/components/schemas/ScanRunRef'
          nullable: true
    ScanEffectiveConfig:
      type: object
      description: >-
        What the server actually resolved for this scan, as opposed to what the
        request asked for.
      required:
        - scanners
        - enrichments
        - coverage
        - policy_snapshot
      properties:
        fetch_lfs_models:
          type: boolean
          description: >-
            Immutable Git LFS download choice resolved at submission. Absent on
            older scans.
        scanners:
          type: array
          items:
            $ref: '#/components/schemas/ScannerKey'
        enrichments:
          type: array
          items:
            $ref: '#/components/schemas/EnrichmentKey'
        coverage:
          $ref: '#/components/schemas/ScanCoverage'
        policy_snapshot:
          $ref: '#/components/schemas/PolicySnapshot'
    ScanNarrowing:
      type: object
      description: >-
        One adjustable field the server resolved to something other than the
        request asked for. Non-adjustable requests are rejected with a 4xx
        instead of being silently narrowed.


        Coverage is the only adjustable field today, and its two outcomes are
        both terminal: a downgrade to `partial` is honoured exactly as asked,
        and a promotion to `full` is refused with `coverage_promotion_rejected`.
        So `narrowed_from_request` is empty on every submission the server
        currently accepts. It is populated, not omitted, because `[]` is the
        positive statement "the server honoured this submission as sent" — and
        because the next adjustable field reports through it.
      required:
        - field
        - requested
        - effective
        - reason
      properties:
        field:
          type: string
          enum:
            - coverage
          description: The adjustable field. `coverage` is the only one today.
        requested:
          type: string
        effective:
          type: string
        reason:
          type: string
          description: Machine-readable reason code for the narrowing.
    ScanGate:
      type: string
      enum:
        - pass
        - warn
        - block
        - require
        - error
        - none
      description: >-
        A scan's collapsed policy outcome. Precedence is `error > block >
        require > warn > pass`.


        `none` is the distinct non-enforcing result for a scan no policy was in
        force for. It is never rendered as `pass` — nothing was checked, so
        nothing passed — and never as `error`, because no configured policy went
        unanswered. That holds however the scan itself ended: a failed or
        cancelled scan on a project with no policies is still `none`, and its
        own `status` is what says the run did not finish.


        A scan whose every policy in force did not apply to it is `none` too:
        each of those policies reads only a scanner the scan's selection left
        out, so no policy applied. `GET /v1/scans/{scanId}/policy-verdicts`
        lists them with verdict `not_applicable`.
    ScanGateReason:
      type: string
      enum:
        - no_policy_applies
        - all_policies_passed
        - policy_warned
        - approval_required
        - policy_blocked
        - missing_evidence
        - evaluation_failed
      description: >-
        The highest-precedence cause of the gate, not a summary of every policy.
        It pairs with `gate`:

         - `none` → `no_policy_applies`, including when every policy in force did not apply to the scan
         - `pass` → `all_policies_passed`
         - `warn` → `policy_warned`
         - `require` → `approval_required`
         - `block` → `policy_blocked`
         - `error` → `missing_evidence` when a policy in force could not be evaluated because an enrichment it reads is absent (a policy that reads only a scanner the scan left out is not applicable instead, and does not count), or `evaluation_failed` when evaluation itself errored, or when the scan never reached an evaluation a policy WAS waiting on. A scan that never reached one because nothing was in force is `none`, not `error`.
    ScanPolicyEvaluation:
      type: object
      description: >-
        The state of one scan's policy evaluation, reported by the Scan
        resource. `GET /v1/scans/{scanId}/policy-verdicts` does not carry it:
        deciding an evaluation's status needs the scan's own lifecycle, which
        only this resource knows.
      required:
        - status
        - policies_evaluated
      properties:
        status:
          $ref: '#/components/schemas/ScanPolicyEvaluationStatus'
        evaluated_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the scan-anchored evaluation ran — the earliest `started_at`
            among the evaluations this scan is linked to. Null whenever none is
            recorded: a scan that has not reached policy evaluation, and a
            completed scan no policy was in force for.
        policies_evaluated:
          type: integer
          minimum: 0
          description: >-
            How many policies this scan is linked to an evaluation for, not
            counting the ones that did not apply to it (verdict
            `not_applicable`).
    CodebaseDivergence:
      type: object
      description: >-
        Read-time codebase-divergence result for upload scans. Null for
        git-sourced scans (connected repos are exempt) and for scans where no
        prior inventory exists (first scan of a project).


        `is_divergent` is set when:
         1. The project already had >= 5 prior component PURLs (reliable baseline).
         2. Jaccard overlap between this scan's PURLs and the project's prior PURLs is below 0.15 (15 %).
      required:
        - is_divergent
        - overlap_pct
        - prior_components
      properties:
        is_divergent:
          type: boolean
          description: >-
            True when the project has a sufficient prior inventory AND this
            scan's component overlap is below the low-overlap threshold. A
            non-blocking warning: the scan is still accepted and reconciled
            normally.
        overlap_pct:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: >-
            Jaccard similarity coefficient (|A ∩ B| / |A ∪ B|) over component
            PURL sets: 1.0 = full overlap, 0.0 = no overlap.
        prior_components:
          type: integer
          description: >-
            Number of distinct component PURLs in the project's prior inventory
            (from this project's other completed scans). 0 means this is the
            first scan.
    ScanPublicationBlock:
      type: object
      required:
        - state
        - targets
      properties:
        state:
          allOf:
            - $ref: '#/components/schemas/ScanPublicationState'
          description: >-
            The targets collapsed into the one state a client acts on:
            `degraded` if any target is (it is the only state that needs a
            human), else `pending` while any is in flight, else `published` when
            every open target published; a fully closed set reports `superseded`
            or `cancelled`.
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ScanPublication'
          description: One row per target, delivery priority order.
    ScanTriggerOutcome:
      type: string
      enum:
        - created
        - reused
        - superseded
      description: The append-only result of a submission trigger.
    ScanProducer:
      type: string
      enum:
        - ui_upload
        - connected_repo
        - pr_ci
        - cli
        - pre_commit
        - mcp
        - sbom_import
      description: >-
        The surface that submitted the scan (GLOSSARY "Producer"). Derived from
        the authenticated actor wherever the actor determines it; a
        client-declared value the actor cannot legitimately produce is
        overwritten server-side, never rejected.


        `pre_commit` and `mcp` classify the run as a Self-check: it runs the
        same scanners, enrichments and policy engine and shows results, verdict
        and a deep link under the Project, but materializes no Findings, never
        touches posture, is held at `partial` coverage, is purged 30 days after
        creation and leaves a `selfcheck.*` decision log instead of
        `finding.detected`.


        A Self-check is read through `/v1/self-checks`, not `/v1/scans`: the
        Scan endpoints return governed Scans only.
    ScanActorKind:
      type: string
      enum:
        - user
        - api_key
        - integration
        - worker
      description: >-
        The kind of identity that submitted the scan. `integration` is a
        provider Connection (a GitHub App installation); `worker` is an internal
        job such as the reconcile sweep.
    ScanProvider:
      type: string
      pattern: ^[a-z][a-z0-9-]{0,31}$
      description: >-
        The source-code provider the submission originated from, such as github
        or gitlab. Any connected provider's name.
    ScanRepositoryRef:
      type: object
      description: The provider repository the submitted code belongs to.
      required:
        - external_id
        - full_name
      properties:
        external_id:
          type: string
          description: >-
            The provider's immutable repository id (GitHub's numeric repo id,
            GitLab's project id) as a string. Survives rename and transfer.
        full_name:
          type: string
          description: Display path in `owner/name` form. Mutable — never a match key.
    ScanChangeRequestRef:
      type: object
      description: >-
        The pull/merge request the submission belongs to. An *identified* one
        makes the scan `partial` — at least one of `number`, `url`, `base_sha`,
        `head_sha` or `head_ref` must be set for it to count. An empty object
        narrows nothing, because a client that had been silently narrowed could
        not ask for `full` again without deleting the provenance it wanted.


        Note this applies to a `git` submission too, not only a diff upload. A
        pipeline that wants full-coverage posture submits without change-request
        provenance.
      properties:
        number:
          type: integer
          description: Provider-visible PR/MR number.
        url:
          type: string
          description: Deep link back to the change request.
        base_sha:
          type: string
          description: The commit the change request is based on.
        head_sha:
          type: string
          description: The commit the submitted code was taken at.
        base_ref:
          type: string
          description: The branch the change request targets.
        head_ref:
          type: string
          description: The change request's source branch.
    ScanRunRef:
      type: object
      description: The CI job that submitted the scan — a link back, never a match key.
      properties:
        ci_system:
          type: string
          description: e.g. `github_actions`, `gitlab_ci`, `jenkins`.
        url:
          type: string
          description: Deep link to the CI run.
        external_id:
          type: string
          description: The CI system's own run identifier.
    ScannerKey:
      type: string
      enum:
        - oss
        - crypto
        - ai
      description: >-
        A scanner phase selected for source-code scan compute. `ai` is AI
        provenance. A Self-check does not run it, and an explicit request for it
        on a Self-check answers 400 `invalid_scanners`.
    PolicySnapshot:
      type: object
      description: >-
        The set of `(policy, revision)` in force for the project when the scan
        was created. Immutable: later policy edits never alter it.
      required:
        - policies
      properties:
        policies:
          type: array
          items:
            $ref: '#/components/schemas/PolicySnapshotEntry'
    ScanPolicyEvaluationStatus:
      type: string
      enum:
        - pending
        - completed
        - failed
      description: |-
        Whether this scan has a policy answer yet:

         - `pending` — the scan has not reached policy evaluation. `gate` is null: an unfinished scan has no gate, which is not the same as passing.
         - `completed` — evaluation ran; `gate` is final for this scan and no later policy edit changes it.
         - `failed` — the scan could not produce a complete evaluation, so `gate` is `error`.
    ScanPublicationState:
      type: string
      enum:
        - pending
        - publishing
        - published
        - degraded
        - superseded
        - cancelled
      description: >-
        - `pending` / `publishing` — the provider has not accepted the current
        content yet; retries are automatic (backoff with jitter, at most eight
        attempts over roughly two hours).
         - `published` — the provider holds the current content.
         - `degraded` — a permanent provider answer (401/403/404/410/422) or the retry budget ran out. Only the explicit **Retry publication** action re-opens it; nothing re-scans.
         - `superseded` — a newer head replaced the scan before this publication reached the provider.
         - `cancelled` — reserved for a scan cancelled before it published; today a user-cancelled or idle-timed-out scan republishes its check with a `cancelled` conclusion instead (the row itself stays `published`), so this state does not appear yet.
    ScanPublication:
      type: object
      required:
        - target
        - state
        - attempts
        - revision
      properties:
        revision:
          type: integer
          format: int64
          description: >-
            How many times this placement's CONTENT has been revised. It starts
            at 1 and increases whenever Earnie asks for something different to
            be placed at the same target — a new gate after a Policy Approval,
            or the non-conclusive `base_outdated` verdict after the default
            branch moved beneath the pull request. Re-requesting identical
            content is a no-op and does not move it.


            It is how a republication is observed from outside: the target is
            the same row, the state returns to `pending`, and this number is
            what says the content behind it changed rather than a retry of the
            same content. It is also the fence every terminal outbox write is
            conditioned on, so a slow worker can never record a verdict for
            content that has already been superseded.
        target:
          type: string
          enum:
            - check
            - summary_comment
            - review
          description: >-
            One placement of the scan outcome in the provider. `check` (the
            `Earnie` check run per head SHA), `summary_comment` (one
            Earnie-owned comment per pull request, edited in place), and
            `review` (one `COMMENT` review per scan with inline finding
            comments) all ship.
        state:
          $ref: '#/components/schemas/ScanPublicationState'
        attempts:
          type: integer
          description: Provider attempts spent on the current content.
        provider_ref:
          type: string
          description: >-
            The provider's id for the placed resource (the check run id, comment
            id, or review id), once known. A cache: idempotency finds Earnie's
            own resource before writing, so a lost reference never duplicates a
            placement.
        error_class:
          type: string
          enum:
            - retryable
            - permanent
          description: >-
            Present after a failure. `retryable` (transport, 5xx, 429) is
            retried automatically; `permanent` degrades immediately, and a 401
            or 403 also triggers the Connection health check.
        last_error:
          type: string
          description: The most recent provider failure, sanitized.
        next_attempt_at:
          type: string
          format: date-time
          description: When the next automatic attempt is due, while `pending`.
        published_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PolicySnapshotEntry:
      type: object
      description: One policy and the immutable revision it was in force at.
      required:
        - policy_id
        - revision
      properties:
        policy_id:
          type: integer
          format: int64
        revision:
          type: string
          description: >-
            The policy's content hash (`sha256:<hex>`) — the same value the
            policy evaluator records as `policy_hash`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An Earnie API key, sent as `Authorization: Bearer sk_earnie_...`. Create
        one under Settings > API keys. The key's scopes decide which operations
        it may call.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.