API overview

The Monolith REST API exposes the same primitives the web and desktop apps use: API keys, Artifacts, Marks, Organizations.

Base URL


https://api.joinmonolith.com

Versioning

Versioned endpoints live under /api/v1/*. Breaking changes mint a new prefix (/api/v2/*); v1 keeps working for a deprecation window. Within v1, additive changes (new fields, new endpoints) are not breaking and ship without notice.

Authentication

Every endpoint requires a bearer token:


Authorization: Bearer <token>

Two token formats are accepted on /api/v1/*:

Monolith JWT — issued by the Monolith auth service; standard 7-day lifetime
API key — monolith_<22 base62 chars>, minted from the Monolith dashboard by an organization owner on the enterprise tier. Authenticates as its organization; valid until revoked or until the workspace is frozen.

See Authentication for the full lifecycle and revocation flow.

Creating an API key

API keys are minted through the Monolith dashboard at pro.joinmonolith.com , not via the API itself. See Authentication for the step-by-step flow with screenshots.

The API key secret is shown only once, immediately after creation. Copy it into your secrets manager before closing the dialog — it cannot be retrieved later. If lost, revoke the key and mint a new one.

Content types

All request bodies are application/json unless noted otherwise.
POST /api/v1/artifacts also accepts multipart/form-data, which adds an optional file part carrying the asset bytes. See Attaching the asset.
All responses are application/json (errors included).
Timestamps are ISO 8601 strings (2026-05-03T17:00:00Z).
Identifiers are UUIDs (format: uuid) unless they’re fingerprints (^0x[0-9a-f]{64}$).

Attaching the asset on `POST /api/v1/artifacts`

An Artifact is always signed against the fingerprint you send. Attaching the bytes is optional and changes exactly one thing: what the published C2PA manifest report (c2paAssets.manifestUrl) can attest to.

Request	`validation_state` in the report
`application/json` (no file)	omitted — the `c2pa.hash.data` hard binding can’t be checked without the asset
`multipart/form-data` with `file`	`"Valid"` — every check ran, hard binding included

In both cases the report’s validation_results carry the checks that genuinely ran (claim signature, certificate chain, timestamp, assertion hashed-URIs). An omitted validation_state means “the binding is yours to verify”, not “invalid”.

The attached bytes are used only to produce that report from a verifying read-back. They are never stored. The upload must hash (SHA-256) to fingerprint — a mismatch is a 400.

Idempotency

POST /api/v1/artifacts is fingerprint-idempotent: if a non-failed Artifact already exists for the fingerprint, the call is rejected. Retries on transient errors are safe to repeat with the same body.
DELETE /api/v1/api-keys/{keyId} is idempotent only on first call; subsequent calls return 404. JWT callers must include ?organizationId=<uuid>; API-key callers omit it.

Caching

GET /api/v1/marks (the Mark list) is cached server-side for 60 seconds per user. Cache misses are transparent to the caller.

Endpoints at a glance

Method	Path	Purpose
`POST`	`/api/v1/api-keys`	Mint a key for an organization (enterprise tier)
`GET`	`/api/v1/api-keys`	List active keys for an organization (cropped form)
`DELETE`	`/api/v1/api-keys/{keyId}`	Revoke a key
`POST`	`/api/v1/artifacts`	Create an Artifact from a fingerprint (JSON, or multipart with the optional asset)
`GET`	`/api/v1/artifacts/{fingerprint}`	Fetch the Artifact bound to a fingerprint
`GET`	`/api/v1/marks`	List Marks visible to the caller (optional `?organizationId=` filter)
`GET`	`/api/v1/marks/{markId}/artifacts`	Paginated Artifact list per Mark
`GET`	`/api/v1/organizations`	List the caller’s organizations

The full schema-aware reference with try-it-out lives at /api/reference.