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.
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}$).

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
`GET`	`/api/v1/artifacts/{fingerprint}`	Fetch the Artifact bound to a fingerprint
`GET`	`/api/v1/marks`	List Marks the caller can write to
`GET`	`/api/v1/marks/{projectId}/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.