SDK 0.7.3a4 developer alpha · documentation updated 2026-11-14.
Versioned benchmark and legal-source review dates below remain historical evidence; they are not a new qualification or legal approval of this candidate.
This reference describes this candidate command surface. Run ariadne --help
and a command's --help in the provisioned environment for all options.
Main commands
| Command | Purpose | Important inputs |
|---|---|---|
setup media / setup video |
Explicit pinned installation | --fetch-models, optional bootstrap cache/wheelhouse |
runtime check |
Inspect native/wrapper pair and hash | No implicit repair |
models fetch / models check |
Provision/inspect selected engines | --engine auto (default), media, all, trustmark, video, or videoseal |
init-dev DIRECTORY |
Generate local evaluation identity | Explicit development use only |
profile init / profile sources / profile check CONFIG |
Template, source catalog, requirement planning | --as-of YYYY-MM-DD changes evaluation date, not source knowledge |
kit init DIRECTORY |
Create a new deployment | --publisher, --system, --system-version; development is opt-in |
kit check DIRECTORY --runtime |
Local configuration/runtime checks | No live endpoint or legal verdict |
kit render DIRECTORY |
Regenerate deployment config | Run after endpoint/limit changes |
kit export DIRECTORY BATCH |
Batch export with resident workers | Relative paths, actual timestamps, per-job video profile |
kit serve DIRECTORY |
Run the configured verifier | Isolated inference, separate report key |
mark SOURCE DESTINATION |
Mark, sign and read back | Identity, source facts/time; optional profile, registry, disclosure |
verify SOURCE |
Check supported evidence | Optional roots/registry, --verification-scope all|current, and --strict |
recover SOURCE DESTINATION |
Recover a detached manifest | Registry, --verification-scope all|current; output file must be new |
report keygen DIRECTORY / report verify RECEIPT |
Separate Ed25519 report keys and offline verification | Pinned --public-key; optional --asset, --verifier-id |
feedback-summary DATABASE |
Read anonymous aggregate counts | Existing feedback database |
--trust-anchors configures manifest issuer roots; --tsa-trust-anchors
configures private TSA roots separately. A report key, provider key and TLS key
have different functions. See trust operations.
Python objects
SDK accepts a marking adapter, signing identity, optional registry, issuer/TSA
roots and a video_profile. Reuse one instance per worker process, after fork;
close it on shutdown. SDK.mark(source, destination, record, ...) is synchronous.
A per-export profile override must agree with any supplied product configuration.
SDK.verify(path) checks evidence; SDK.recover_manifest(source, destination)
validates and saves the registered manifest without modifying the submitted file.
When several IDs are found it refuses an automatic choice; pass token= (CLI
recover --id) to select one confirmed ID after detection. The selector is never
given to the detector.
See the runnable integration pattern.
ProvenanceRecord contains publisher, system name/version, image/video kind,
created/altered action, timezone-aware generation time and a random UUIDv4.
It is a publisher claim, not proof of the factual truth of those fields. Export
and signing reject creation times over five minutes in the future; parsing
external records remains possible. The allowance is an SDK clock-skew policy.
Result interpretation
| Evidence | Meaning |
|---|---|
c2pa.status=verified_claim |
Signature and supported asset binding validated; inspect issuer trust and development status separately |
watermark.status=recovered_claim |
Supported ID recovered; not a factual-truth or whole-video certificate |
not_found |
Scoped check completed without a supported mark |
not_checked |
Check incomplete/unavailable; not a successful negative |
single_observation |
A video ID was observed once without sufficient corroboration |
multiple_ids |
Several distinct watermark IDs were read. Each is listed in watermark.ids with its scheme, basis (confirmed/observed) and observed positions. No ID is chosen for the file, and several IDs do not by themselves invalidate a C2PA signature |
c2pa.status=invalid |
Invalid credential; c2pa.reason gives the cause. Watermark evidence is reported separately |
token_mismatch |
One recovered ID differs from the signed claim: conflicting claims, not by itself an invalid signature |
expired_credential |
Acceptable signing time could not be established for an expired credential |
Registry content_binding=not_verified |
ID association exists; edited copy is not authenticated by that association |
An incomplete negative headline is Check incomplete. Existing positive or
invalid evidence is retained. Inspect structured fields, not only the label.
Video sample coverage is not the percentage of the whole video carrying a mark.
watermark.evidence_scope lists each pass (scheme, selection, unique frames,
time range, stop reason) and whole_file_examined; an ID applies only to the
positions where it was read. With several IDs, recovery.status=per_id gives one
registry result per confirmed ID, bound to the schemes that read it.
Report schema_version 2 (shipped in 0.7.3a4): the former watermark
invalid with reason multiple_tokens/conflicting_ids is now
multiple_ids with watermark.ids. Single-ID results keep their fields.
Exit codes and HTTP
Most successful commands return 0; argument, operational and verification failures
return 2. profile check uses 3 for open actions/review. An ordinary verify
can return 0 for a completed not_found; parse the result. verify returns 0
only for watermark recovered_claim/not_found without a C2PA failure or ID
mismatch; multiple_ids, single_observation and incomplete checks return 2. --strict requires
a valid, non-development credential and trusted issuer, otherwise 2.
The verifier accepts raw binary POST /verify?format=png|jpg|jpeg|mp4, not
multipart. It exposes UI, /health, /openapi.json, report public-key endpoints,
/records/{token} and feedback. A signed response is verified with a separately
pinned report public key and, when needed, the submitted asset digest. See
signed reports and recovery endpoints.
Full-manifest routes are disabled unless explicitly enabled; only approved
records are published. HTTP 429 indicates capacity/rate limits, not a negative
media result. TLS edge and application upload ceilings can differ.
Detection scope and model selection
verify, recover and serve accept --verification-scope all|current; the
Python SDK also accepts a nonempty finite list of known schemes. Existing SDK/CLI
defaults remain all; new kits explicitly configure current. current promises
Python-Q image checks and video-Q MP4 checks. Python-Q video reads are supplemental
when available: a negative video-Q result is not a check of the older Python-Q
MP4 scheme. A signed Python-Q MP4 also requires that historical decoder; provision
the media runtime. all retains legacy VideoSeal and Python-Q video obligations.
configured_schemes records the operator configuration; declared_schemes is the
file-specific obligation. completed_schemes lists completed declared checks only
(always a subset of declared_schemes); a supplemental reader that also finished,
such as Python-Q on a current-scope MP4, is in supplemental_completed_schemes.
A positive early stop is not a completed negative; the ID is in watermark.ids.
For a declared legacy Python-Q MP4 the documented procedure is five uniformly
requested positions. Missing required decoders or expired budgets never become a
completed negative.
No input C2PA claim, including a trusted non-development issuer's claim, can
narrow the operator's declared checks. Explicit all retains every historical
scheme for that media; a custom list also retains its obligations. A broad public
CA trust store does not authorize third-party signers to skip local history.
Missing historical decoders are reported as incomplete coverage, even if the
trusted claim names a current algorithm. If the trusted claim names a technique
outside the operator scope, the primary result
is kept, signed_scheme_unchecked names the claimed technique and a negative
becomes not_checked (signed_scheme_out_of_operator_scope). The reported
signed_routing makes the routing visible. signed_id_observed is true on an
actual matching read, false after performed nonmatching observations, and null
when observation was not established. A partial scan can still have a true value.
Bare models fetch/check uses auto: current media if Python TrustMark is
installed, otherwise video-only, with selection/skips printed. Explicit media
requires both current runtimes; explicit all retains its legacy requirements.
No request handling downloads models.
POST /matches/byContent rejects an explicit algorithm outside this file's
operator scope with HTTP422 algorithm_outside_operator_scope / not_checked.
An in-scope requested technique without completed negative or matching positive
evidence returns HTTP503 incomplete_content_search, never an empty successful
search. These outcomes are separate from a completed HTTP200 empty match list.
Authenticated TSA options
mark accepts --timestamp-credential-file PATH, --timestamp-timeout SECONDS
and --timestamp-ca-bundle PATH with --timestamp-url. The file contains a bearer
token and must be a regular owner-only file. Authenticated timeout: >0 to 25s;
the HTTPS CA bundle is separate from timestamp signer trust. Kit equivalents
and offline qualification boundaries are described in
authenticated timestamping.