Skip to main content
POST
Run a Self-check over an inline SourceSet

Authorizations

Authorization
string
header
required

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.

Body

application/json

Creates a Self-check from an INLINE SourceSet in one request — no plan-folder / ingest / commit-ingest round trips. The server materializes a tmpdir and runs the same pipeline.

Exactly one of files or diff must be present. There is no url or branch: the MCP surface never clones, and a run against a bound repository is a governed Scan through a Connection, not a Self-check.

project_id
string<uuid>
required

The project the submitted code belongs to.

files
object[]

The inline SourceSet. Limits are organization-configurable and start at 200 files, 512 KiB per file and 1 MiB per call. Over the limit is 422 source_set_too_large, which names the cap and the measured size so the caller can fall back to earnie scan diff.

diff
string

A unified diff, as an alternative to files. Its post-image (the + side of every hunk) is materialized as the SourceSet, so a deletion-only diff yields no file to scan. Subject to the same byte caps as files.

name
string

Optional display name. Defaults to a generated label.

scanners
enum<string>[]

Optional scanner set. Omitted runs every scanner enabled for the organization that the caller's API key scanner restriction allows; a disabled or out-of-scope scanner is rejected with 403.

Minimum array length: 1

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.

Available options:
oss,
crypto,
ai
enrichments
enum<string>[]

Optional PURL enrichment list. Omitted defaults to ["vulnerabilities","licenses"]; an explicit empty array runs no optional enrichments.

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"].

Available options:
vulnerabilities,
licenses
scan_context
object | null

Submission provenance. producer is resolved server-side as on every other creation path; a producer the actor cannot legitimately be is overwritten. This endpoint only ever creates a Self-check, so a resolved producer outside {pre_commit, mcp} is refused with 422 producer_not_self_check rather than silently downgraded.

wait_seconds
integer

How long the server may hold the request waiting for the run to reach a terminal state. Zero or omission uses the organization's configured budget (default 45 s — a pre-commit hook allows 60 s and an agent client's default tool timeout is around 60 s). Past the budget the response is 200 with status: running and the Self-check's id; the caller polls GET /v1/self-checks/{selfCheckId}.

Required range: 0 <= x <= 120

Response

The Self-check. status is completed/failed when the run finished within the budget, running when it did not.

A Self-check.

id
string<uuid>
required
project_id
string<uuid>
required
project
object
required

Light reference to a linked project (denormalised for list rendering).

status
enum<string>
required

A Self-check's lifecycle, collapsed from the underlying run's status. running covers every non-terminal state: the caller polls, or the creation call returned past its synchronous budget.

There is no cancelled here: a cancelled run reports failed. The receiving-idle sweep cancels a Self-check whose client stopped uploading, and running would never resolve.

Available options:
running,
completed,
failed
coverage
enum<string>
required

Always partial. An inline SourceSet is a subset of a codebase and a Self-check may never mark a Project's findings absent.

Available options:
full,
partial
producer
enum<string>
required

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.

Available options:
ui_upload,
connected_repo,
pr_ci,
cli,
pre_commit,
mcp,
sbom_import
created_by
object
required

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.

created_at
string<date-time>
required
expires_at
string<date-time>
required

When the retention sweep purges this Self-check — 30 days after creation. The selfcheck.* decision log outlives it: audit retention is the general one.

files
object
required

The inline SourceSet boundary decided by the shared keep plan, before scanner-specific progress counters run. Manifests count as included because dependency detection evaluates them even when OSS fingerprinting does not.

scanners
object[]
required

Every scanner Earnie knows, with whether this run executed it. Empty until the submission is resolved; complete from the first response on.

evaluated
object
required

How much the Self-check actually evaluated.

not_evaluated
object[]
required
violations
object[]
required
url
string
required

Deep link to the Self-check under its Project.

name
string
gate
enum<string> | null

The Self-check's collapsed policy outcome. Same vocabulary and same precedence as a Scan's gate — error > block > require > warn > pass, with none the distinct non-enforcing result when no policy applied. Null while status is running.

Available options:
pass,
warn,
block,
require,
error,
none
finished_at
string<date-time> | null
files_total
integer
deprecated

Scanner progress count retained for compatibility. Use files for the submitted/included/excluded SourceSet boundary; this value may exclude manifests consumed by dependency detection.

error_code
string | null
error_message
string | null