MilliHash API (v1.0.0)

Download OpenAPI specification:

MilliHash REST API for asset registration, verification, project lineage, portfolio management, and opt-in similarity search.

Hosts

  • https://free-api.millihash.io — public verification, stats, and sample proof
  • https://millihash.p.rapidapi.com — authenticated registration, portfolio, projects, similarity, plan, plus the same public verification routes
  • https://app.millihash.com — operator admin audit (Auth0 JWT)

Authenticated routes require X-RapidAPI-Key. Public verification routes require no auth.

Admin Audit

Operator audit search (Auth0 JWT)

Search audit events

Read-only audit search. Filters AND together; omitted parameters are wildcards. Paginated; max 200 items per page. Requires Auth0 JWT with audit:read.

Authorizations:
Auth0Bearer
query Parameters
eventType
string

Exact event type filter

from
string <date-time>

Inclusive lower bound on occurredAt (ISO-8601)

to
string <date-time>

Inclusive upper bound on occurredAt (ISO-8601)

hash
string^[0-9a-f]{64}$

Proof digest hex associated with the event

certificateId
string <uuid>

Certificate UUID associated with the event

userId
string

Actor / registrant user id

cursor
string

Opaque cursor from a prior nextPageCursor

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "items": [
    ],
  • "nextPageCursor": "string",
  • "resultCount": 0
}

Registrations

Register assets and refresh discovery fingerprints

Register an asset

Hash the asset (or accept a client-supplied SHA-256), timestamp a version commitment with RFC 3161 TSA, persist the registration, and enqueue Bitcoin anchoring.

  • JSON — text (text) or client-supplied (hash); no body contentType.
  • Multipart — required file + optional mediaType (sniff if omitted).
  • Asset bytes are never stored — only digests and metadata.
  • Same proof digest by the same caller → 409; other callers may succeed with a prior-registration notice.
Authorizations:
RapidApiKey
Request Body schema:
required
submissionMode
required
string
Value: "server-computed"

Must be server-computed for multipart uploads

registrantRole
required
string
Enum: "creator" "witness"

Self-declared relationship to the asset. Not verified; immutable after create. Omitted/blank/unknown → 400 REGISTRANT_ROLE_REQUIRED.

label
string <= 200 characters

Immutable display label; omit/blank → permanently empty

labelPublic
boolean
Default: false

Show label on public verify; forced false when label empty. Mutable via PATCH.

internalLabel
string

Private name; never on certificates or public APIs

mediaType
string

Optional MIME. Sniffed when omitted or application/octet-stream. Unresolved → 400 MEDIA_TYPE_UNRESOLVED; sniff mismatch → 400 MEDIA_TYPE_MISMATCH. text/* file bytes must be valid UTF-8.

file
required
string <binary>

Asset bytes (prefer JSON { text } for pure text)

similarityOptIn
boolean
Default: false

Opt into similarity indexing. Text-only; binary with true → 400 SIMILARITY_TEXT_ONLY.

discoverability
string
Default: "hidden"
Enum: "hidden" "label_visible"

How this registration appears in similarity results when opted in

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "registrationId": "cb67e1cd-0e53-4115-9a51-243e5b471e8b",
  • "hash": "string",
  • "digests": [
    ],
  • "fingerprintSetVersion": "string",
  • "contentHash": "string",
  • "submissionMode": "server-computed",
  • "registrantRole": "creator",
  • "label": "string",
  • "labelPublic": true,
  • "internalLabel": "string",
  • "discoverability": "hidden",
  • "similarityIndexStatus": "pending",
  • "tsaTimestamp": "2019-08-24T14:15:22Z",
  • "tsaProvider": "string",
  • "certificateUrl": "../dictionary",
  • "keepOriginalsNotice": "string",
  • "c2pa": {
    },
  • "priorRegistrationNotice": {
    }
}

Refresh discovery fingerprints

Re-upload the original asset for a registration you own. Proof digests, version commitment, and original TSA stay unchanged. On success, MilliHash adds discovery fingerprints, advances fingerprintSetVersion, and creates a separately timestamped / anchored FingerprintRefresh.

  • JSON — { "text": "..." } for text registrations.
  • Multipart — file + optional mediaType.
  • Proof match required (any overlapping proof hex); else 409 PROOF_HASH_MISMATCH.
  • Does not consume registration quota.
Authorizations:
RapidApiKey
path Parameters
registrationId
required
string

Registration to refresh (must be yours)

Request Body schema:
required
file
required
string <binary>

Original asset bytes

mediaType
string

Optional MIME; sniffed when omitted (same rules as create)

similarityOptIn
boolean
Default: false

Opt an existing text registration into similarity. Binary with true → 400. Proof mismatch → 409 with no enqueue.

discoverability
string
Default: "hidden"
Enum: "hidden" "label_visible"

Similarity visibility when opting in

Responses

Request samples

Content type
No sample

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "fingerprintRefreshId": "string",
  • "registrationId": "string",
  • "linkKind": "fingerprint_refresh",
  • "sequence": 1,
  • "originalProofHash": "string",
  • "digests": [
    ],
  • "fingerprintSetVersion": "string",
  • "previousFingerprintSetVersion": "string",
  • "tsaTimestamp": "2019-08-24T14:15:22Z",
  • "tsaProvider": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "lineage": {
    },
  • "keepOriginalsNotice": "string",
  • "discoverability": "hidden",
  • "similarityIndexStatus": "pending"
}

Project Lineage

Create projects and append versions

Create a project (genesis version)

Creates a project and version 1 registration from the same JSON/multipart shapes as POST /registrations. Consumes one registration quota unit.

Authorizations:
RapidApiKey
Request Body schema:
required
submissionMode
required
string
Value: "server-computed"

Must be server-computed for multipart uploads

registrantRole
required
string
Enum: "creator" "witness"

Self-declared relationship to the asset. Not verified; immutable after create. Omitted/blank/unknown → 400 REGISTRANT_ROLE_REQUIRED.

label
string <= 200 characters

Immutable display label; omit/blank → permanently empty

labelPublic
boolean
Default: false

Show label on public verify; forced false when label empty. Mutable via PATCH.

internalLabel
string

Private name; never on certificates or public APIs

mediaType
string

Optional MIME. Sniffed when omitted or application/octet-stream. Unresolved → 400 MEDIA_TYPE_UNRESOLVED; sniff mismatch → 400 MEDIA_TYPE_MISMATCH. text/* file bytes must be valid UTF-8.

file
required
string <binary>

Asset bytes (prefer JSON { text } for pure text)

similarityOptIn
boolean
Default: false

Opt into similarity indexing. Text-only; binary with true → 400 SIMILARITY_TEXT_ONLY.

discoverability
string
Default: "hidden"
Enum: "hidden" "label_visible"

How this registration appears in similarity results when opted in

Responses

Request samples

Content type
No sample

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "label": "string",
  • "labelPublic": true,
  • "internalLabel": "string",
  • "registrationId": "cb67e1cd-0e53-4115-9a51-243e5b471e8b",
  • "versionNumber": 1,
  • "documentHash": "string",
  • "digests": [
    ],
  • "contentHash": "string",
  • "certificateUrl": "string",
  • "chainVerifyUrl": "/projects/{projectId}/chain/verify"
}

Append a project version

Adds version N+1 with a chained contentHash. Send X-Project-Head-Content-Hash equal to the current head commitment or the request fails with a head conflict (409).

Authorizations:
RapidApiKey
path Parameters
projectId
required
string <uuid>

Project to append to (must be yours)

header Parameters
X-Project-Head-Content-Hash
required
string^[0-9a-f]{64}$

Current head contentHash (optimistic concurrency / CAS)

Request Body schema:
required
submissionMode
required
string
Value: "server-computed"

Must be server-computed for multipart uploads

registrantRole
required
string
Enum: "creator" "witness"

Self-declared relationship to the asset. Not verified; immutable after create. Omitted/blank/unknown → 400 REGISTRANT_ROLE_REQUIRED.

label
string <= 200 characters

Immutable display label; omit/blank → permanently empty

labelPublic
boolean
Default: false

Show label on public verify; forced false when label empty. Mutable via PATCH.

internalLabel
string

Private name; never on certificates or public APIs

mediaType
string

Optional MIME. Sniffed when omitted or application/octet-stream. Unresolved → 400 MEDIA_TYPE_UNRESOLVED; sniff mismatch → 400 MEDIA_TYPE_MISMATCH. text/* file bytes must be valid UTF-8.

file
required
string <binary>

Asset bytes (prefer JSON { text } for pure text)

similarityOptIn
boolean
Default: false

Opt into similarity indexing. Text-only; binary with true → 400 SIMILARITY_TEXT_ONLY.

discoverability
string
Default: "hidden"
Enum: "hidden" "label_visible"

How this registration appears in similarity results when opted in

Responses

Request samples

Content type
No sample

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "registrationId": "cb67e1cd-0e53-4115-9a51-243e5b471e8b",
  • "versionNumber": 2,
  • "documentHash": "string",
  • "digests": [
    ],
  • "contentHash": "string",
  • "headContentHash": "string",
  • "certificateUrl": "string"
}

Registrant Portfolio

List registrations/projects and download certificates

List your registrations

Cursor-paginated registry of registrations you own (page size 50). Default sort: tsaTimestamp descending. Optional sort / direction; tie-break is always registrationId ascending. Rows include digests, labels, display name, and anchor state (no per-row anchor lookup).

Authorizations:
RapidApiKey
query Parameters
cursor
string

Opaque cursor from a prior nextPageCursor. Omit for the first page.

sort
string
Default: "tsaTimestamp"
Enum: "tsaTimestamp" "label" "bitcoinBlockConfirmationTime"

Primary sort field. label uses display-name order (internalLabel, then label). Default tsaTimestamp.

direction
string
Enum: "asc" "desc"

Sort direction. Defaults: tsaTimestamp / bitcoinBlockConfirmationTime → desc; label → asc.

Responses

Response samples

Content type
{
  • "items": [
    ],
  • "nextPageCursor": "string"
}

Update registration labels

Patch any subset of labelPublic, internalLabel, and discoverability. Immutable label and proof digests are rejected. labelPublic=true with an empty label → 400. discoverability requires similarity opt-in → else 400 SIMILARITY_NOT_OPTED_IN.

Authorizations:
RapidApiKey
path Parameters
registrationId
required
string <uuid>

Registration to update (must be yours)

Request Body schema:
required
labelPublic
boolean

Show label on public verify responses (requires non-empty label)

internalLabel
string or null

Private name; size limited by plan maxInternalLabelLength

discoverability
string
Enum: "hidden" "label_visible"

Similarity result visibility; requires similarity opt-in

Responses

Request samples

Content type
{
  • "labelPublic": true,
  • "internalLabel": "string",
  • "discoverability": "hidden"
}

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "registrationId": "cb67e1cd-0e53-4115-9a51-243e5b471e8b",
  • "label": "string",
  • "labelPublic": true,
  • "internalLabel": "string",
  • "discoverability": "hidden"
}

Download certificate PDF

Renders the certificate PDF on demand for a registration you own. Same renderer version → byte-identical PDFs on repeat download.

Authorizations:
RapidApiKey
path Parameters
certificateId
required
string <uuid>

Certificate UUID

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "errors": [
    ]
}

Download anchored certificate PDF

Renders the Layer-1 + Bitcoin-anchored certificate PDF when the anchor is Confirmed. Pending / Stamped / Failed → 409 ANCHOR_NOT_CONFIRMED.

Authorizations:
RapidApiKey
path Parameters
certificateId
required
string <uuid>

Certificate UUID

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "errors": [
    ]
}

List your projects

Cursor-paginated list of projects you own (page size 50). Ordered by createdAt descending, then projectId ascending.

Authorizations:
RapidApiKey
query Parameters
cursor
string

Opaque cursor from a prior nextPageCursor. Omit for the first page.

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "items": [
    ],
  • "nextPageCursor": "string"
}

Get project detail

Returns a project you own, including an ordered version timeline.

Authorizations:
RapidApiKey
path Parameters
projectId
required
string <uuid>

Project id (must be yours)

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "project": {
    },
  • "versions": [
    ]
}

Public Verification

Verify assets, certificates, anchors, chains; public stats and sample

Verify a project chain

Checks sequential version numbers and contentHash links for a project. Public; no ownership required.

path Parameters
projectId
required
string <uuid>

Project UUID

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "status": "valid",
  • "label": "string",
  • "versionCount": 0,
  • "message": "string",
  • "versions": [
    ]
}

Verify an asset

Hash the upload with the same normalization as registration and look up exact proof matches.

  • Multipart — contentType=binary + file.
  • JSON — contentType=text + text.
  • Does not re-extract C2PA from the upload; echoes stored metadata only.
Request Body schema:
required
contentType
required
string
Value: "binary"

Must be binary for multipart verify

file
required
string <binary>

Raw bytes to hash and look up

Responses

Request samples

Content type
No sample

Response samples

Content type
application/vnd.millihash.v1+json
Example
{
  • "hash": "string",
  • "digests": [
    ],
  • "matchedAlgorithm": "string",
  • "matchedTransform": "string",
  • "matchedClass": "proof",
  • "registrantRole": "string",
  • "label": "string",
  • "hitType": "standalone",
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "versionNumber": 0,
  • "chainVerifyUrl": "string",
  • "registrantSnapshot": {
    },
  • "tsaTimestamp": "string",
  • "tsaProvider": "string",
  • "submissionMode": "server-computed",
  • "submissionModeNotice": "string",
  • "semanticsNotice": "string",
  • "certificateVerificationUrl": "http://example.com",
  • "additionalMatchCount": 0,
  • "additionalMatches": [
    ],
  • "c2pa": {
    }
}

Verify a certificate

Look up by certificate UUID or 64-char SHA-256 hex (case-insensitive). Validates the TSA token and optional LTV chain. Does not return anchor state or PDF bytes. shareableUrl is always keyed by certificate id.

path Parameters
id
required
string

Certificate UUID or SHA-256 hex

Responses

Response samples

Content type
application/vnd.millihash.v1+json
Example
{
  • "certificateId": "93038071-4553-48f6-8780-c7262cd9be88",
  • "hash": "string",
  • "digests": [
    ],
  • "label": "string",
  • "registrantRole": "string",
  • "matchedAlgorithm": "string",
  • "matchedTransform": "string",
  • "matchedClass": "proof",
  • "registrantSnapshot": {
    },
  • "tsaTimestamp": "string",
  • "tsaProvider": "string",
  • "submissionMode": "server-computed",
  • "submissionModeNotice": "string",
  • "shareableUrl": "http://example.com",
  • "tsaValidation": {
    },
  • "ltvChain": [
    ],
  • "c2pa": {
    },
  • "semanticsNotice": "string",
  • "additionalMatchCount": 0,
  • "additionalMatches": [
    ]
}

Get Bitcoin anchor status

Look up by certificate UUID or SHA-256 hex. Returns the anchor job snapshot. Certificate validity is independent of anchor state (certificateStillValid is always true on a hit).

path Parameters
registrationId
required
string

Certificate UUID or SHA-256 hex

Responses

Response samples

Content type
application/vnd.millihash.v1+json
Example
{
  • "state": "Pending",
  • "shareableUrl": "http://example.com",
  • "certificateStillValid": true,
  • "otsBase64": "string",
  • "otsDownloadUrl": "http://example.com",
  • "bitcoinBlockConfirmationTime": "2019-08-24T14:15:22Z",
  • "bitcoinBlockConfirmationTimeNote": "string",
  • "estimatedConfirmationWindow": "string",
  • "failureReason": "string",
  • "attemptsExhausted": true,
  • "totalAttempts": 4
}

Download OpenTimestamps proof

Returns raw .ots bytes when the anchor is Confirmed; otherwise 404.

path Parameters
registrationId
required
string

Certificate UUID or SHA-256 hex

Responses

Get public activity stats

Aggregate service activity for public pages. Always includes timestampStandard and anchoring. Optional fields appear only when thresholds are met (never zero-padded). No hashes, labels, or registrant data. Cached up to 60 seconds.

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "timestampStandard": "RFC 3161",
  • "anchoring": "bitcoin-opentimestamps",
  • "latestAnchorConfirmedAt": "2019-08-24T14:15:22Z",
  • "usage": {
    }
}

Get the sample proof

Returns a MilliHash-registered text sample so you can try POST /verify without your own content. Submit text unchanged with contentType=text.

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "text": "string",
  • "certificateId": "string",
  • "registeredAt": "2019-08-24T14:15:22Z",
  • "anchorState": "Pending"
}

Search similar registrations

Embed the query and return ranked opted-in registrations as similarity candidates.

  • Your own registrations can appear as normal rows (isOwn).
  • In idea mode, other users' hidden hits contribute only to privateMatchCount.
  • In wording mode, those hidden hits are omitted entirely.
  • Query text is normalized (text-normalized-v2) before size checks and embedding.
  • Page with limit (default 10, max 50) and cursor from a prior nextPageCursor.
Authorizations:
RapidApiKey
Request Body schema: application/json
required
query
required
string

UTF-8 search text. Blank → 400 QUERY_EMPTY. Size limited by plan maxSimilarityQuerySize after normalization.

mode
string
Default: "idea"
Enum: "idea" "wording"

idea — semantic / topical similarity (lower cosine floor). wording — near-duplicate wording (higher cosine floor); drops others' hidden matches.

includeSamples
boolean
Default: false

When true, include MilliHash sample documents in the candidate pool.

limit
integer [ 1 .. 50 ]
Default: 10

Max rows in this page.

minCosine
number [ 0 .. 1 ]

Optional cosine floor for a hit. When omitted, idea uses ~0.82 and wording uses ~0.95.

cursor
string

Opaque cursor from a previous nextPageCursor for the next page.

Responses

Request samples

Content type
application/json
{
  • "query": "An essay about tidal energy along rocky coasts.",
  • "mode": "idea",
  • "includeSamples": false,
  • "limit": 10
}

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "results": [
    ],
  • "privateMatchCount": 0,
  • "comparedAgainstCount": 0,
  • "message": "Compared against 42 opted-in registrations on MilliHash.",
  • "modelVersion": "string",
  • "nextPageCursor": "string"
}

List built-in similarity samples

Returns MilliHash-authored sample passages with paraphrase, weak, and unrelated query variants for trying search without registering your own text.

Authorizations:
RapidApiKey

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "samples": [
    ]
}

Overlap for an owned opted-in registration

After you opt a registration into similarity, returns earlier candidates that overlap it. While indexing status is pending, results are empty. Caller must own the registration.

Authorizations:
RapidApiKey
path Parameters
registrationId
required
string

Registration to check (must be yours and similarity-opted-in)

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "status": "pending",
  • "results": [
    ],
  • "privateMatchCount": 0
}

Plan

Current plan and upload / query ceilings

Get current plan limits

Returns the caller's subscription plan and byte ceilings for asset upload and similarity query text.

Authorizations:
RapidApiKey

Responses

Response samples

Content type
application/vnd.millihash.v1+json
{
  • "plan": "BASIC",
  • "maxAssetUploadSize": 10485760,
  • "maxSimilarityQuerySize": 65536,
  • "nextPlan": "PRO"
}