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 /api/v1/* endpoint requires a bearer token (the soft binding resolution endpoints are the one public exception — see Soft binding):

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.

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.

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.

Managing Marks

• POST /api/v1/marks creates a Mark and makes the caller its admin. Under JWT auth, organizationId picks the workspace (the caller must be the organization’s owner or an admin member); omit it for a personal Mark. Under API-key auth the Mark always lands in the key’s own organization — naming a different one returns 403 API_KEY_ORG_MISMATCH. Exceeding the workspace’s Mark cap returns 403 TIER_LIMIT_REACHED.
• PUT /api/v1/marks/{markId} is a partial update: only the fields present in the body change, and a Mark’s owning organization can never change. Only the Mark’s admin may call it. API keys act as the organization owner, so a key can update the Marks it created; a Mark another member admins returns 403 FORBIDDEN. Tiers that forbid editing Mark parameters after creation return 403 TIER_RESTRICTION — see Tiers & limits.

Endpoints at a glance

Manifest signing and fingerprint resolution live on a separate, mostly public surface — see Soft binding.