API reference

ClarkCant Marketplace API 1.0.0. The machine-readable document is /openapi.json (OpenAPI 3.1).

Authenticate with Authorization: Bearer <token> (personal API token or OAuth access token) or the browser session cookie. Public reads need no credential.
Writes accept Idempotency-Key; a retry with the same key replays the first result for 24 hours.
Page edits require If-Match with the draft revision id (the page's ETag); a stale value fails with 409.
Errors share one body: {"error": {"code", "message", "requestId", "details"}}.

system

Health and metadata

Operation	Summary	Auth	Headers	Responses
`GET` `/api/v1/health` getHealth	Service health, including a live database round-trip	optional	none	200 500 503

packages

Package listings

Operation	Summary	Auth	Headers	Responses
`GET` `/api/v1/packages` listPackages	List publicly visible packages	optional	none	200 400 500
`GET` `/api/v1/packages/{name}` getPackage	Get one package by npm name (URL-encode scoped names: %40scope%2Fname)	optional	none	200 400 404 500
`GET` `/api/v1/packages/{name}/versions` listPackageVersions	Every indexed version, newest first, with integrity and provenance facts	optional	none	200 400 404 500
`GET` `/api/v1/packages/{name}/install` getPackageInstall	Install coordinate for one exact version (latest unless `version` is given)	optional	none	200 400 404 500

search

Full-text search

Operation	Summary	Auth	Headers	Responses
`GET` `/api/v1/search` searchPackages	Full-text search over publicly visible packages; an empty `q` browses by recency	optional	none	200 400 500

catalog

Categories and collections

Operation	Summary	Auth	Headers	Responses
`GET` `/api/v1/categories` listCategories	All categories with public package counts	optional	none	200 500
`GET` `/api/v1/categories/{slug}` getCategory	One category with its public package count	optional	none	200 400 404 500
`GET` `/api/v1/collections` listCollections	Published editorial collections	optional	none	200 500
`GET` `/api/v1/collections/{slug}` getCollection	One published collection with its public packages, in editorial order	optional	none	200 400 404 500

pages

Published page documents and the page builder admin API (versioned, If-Match guarded)

Operation	Summary	Auth	Headers	Responses
`GET` `/api/v1/pages/{slug}` getPublishedPage	Get the published revision of a page (URL-encode nested slugs: docs%2Finstall)	optional	none	200 400 404 500
`GET` `/api/v1/admin/blocks` listPageBlocks	Registered blocks (props JSON Schema, editor fields) and layouts	optional	none	200 401 403 404 500
`GET` `/api/v1/admin/pages` listPages	All pages, including unpublished ones (pages:write)	optional	none	200 401 403 404 500
`POST` `/api/v1/admin/pages` createPage	Create a page with its first draft revision (pages:write)	optional	if-match, idempotency-key	201 400 401 403 404 409 422 500
`GET` `/api/v1/admin/pages/{pageId}` getPage	Draft document and live revision of a page; the ETag is the draft revision id	optional	none	200 401 403 404 500
`PATCH` `/api/v1/admin/pages/{pageId}` patchPage	Apply a batch of block/SEO operations atomically as one new draft revision	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`PUT` `/api/v1/admin/pages/{pageId}/draft` createPageDraft	Save a whole document as the new draft revision	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`POST` `/api/v1/admin/pages/{pageId}/blocks` addBlock	Add one block to the draft (If-Match: the draft revision)	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`PATCH` `/api/v1/admin/pages/{pageId}/blocks/{blockId}` updateBlock	Merge or replace the props of one block in the draft	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`DELETE` `/api/v1/admin/pages/{pageId}/blocks/{blockId}` removeBlock	Remove one block (and its children) from the draft	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`POST` `/api/v1/admin/pages/{pageId}/blocks/{blockId}/move` moveBlock	Move one block to a new parent or position in the draft	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`PUT` `/api/v1/admin/pages/{pageId}/seo` setPageSeo	Update the page title, description, locale or noindex flag in the draft	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`POST` `/api/v1/admin/pages/{pageId}/preview` previewPage	Create a signed, short-lived preview URL for a revision (the draft by default)	optional	none	200 400 401 403 404 409 422 500
`POST` `/api/v1/admin/pages/{pageId}/publish` publishPage	Publish the current draft revision (requires `pages:publish`)	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`POST` `/api/v1/admin/pages/{pageId}/rollback` rollbackPage	Make a previously published revision live again (If-Match: the currently live revision)	optional	if-match, idempotency-key	200 400 401 403 404 409 422 500
`GET` `/api/v1/admin/pages/{pageId}/revisions` listPageRevisions	Every revision of a page, newest first	optional	none	200 401 403 404 500
`GET` `/api/v1/admin/pages/{pageId}/revisions/{revisionId}` getPageRevision	One immutable revision with its document	optional	none	200 401 403 404 500
`POST` `/api/v1/admin/pages/defaults` ensureDefaultPages	Create and publish the default landing (`home`) and `about` pages if missing (requires `pages:publish`)	optional	none	200 400 401 403 404 409 422 500
`POST` `/api/v1/admin/pages/render` renderPageDocument	Validate and render an unsaved document (builder canvas, Markdown and agent views)	optional	none	200 400 401 403 404 409 422 500

account

The signed-in account, personal API tokens, linked devices and OAuth grants

Operation	Summary	Auth	Headers	Responses
`GET` `/api/v1/me` getMe	The signed-in account, its role and the scopes of the current credential	bearerAuth or sessionCookie	none	200 401 403 500
`DELETE` `/api/v1/me` deleteMe	Delete the account and all data tied to it (needs a signed-in session)	bearerAuth or sessionCookie	none	200 400 401 403 409 500
`GET` `/api/v1/me/packages` listMyPackages	Listings owned by the caller's publishers, in any curation state	bearerAuth or sessionCookie	none	200 401 403 500
`GET` `/api/v1/me/export` exportMe	Download everything stored about the account as JSON	bearerAuth or sessionCookie	none	200 401 403 500
`GET` `/api/v1/me/tokens` listApiTokens	Personal API tokens (metadata only; plaintext is never shown again)	bearerAuth or sessionCookie	none	200 401 403 500
`POST` `/api/v1/me/tokens` createApiToken	Create a scoped personal API token (needs a signed-in session, not a token); the plaintext `token` is returned once, so a replayed Idempotency-Key answers 409 instead of repeating it	bearerAuth or sessionCookie	idempotency-key	201 400 401 403 409 422 500
`DELETE` `/api/v1/me/tokens/{id}` revokeApiToken	Revoke a personal API token (needs a signed-in session, not a token)	bearerAuth or sessionCookie	none	200 401 403 404 500
`POST` `/api/v1/me/devices/link` linkClarkCantDevice	Link a ClarkCant install (local principal prin_*) to this account; idempotent per principal. Needs `devices:link` (offered to OAuth clients) or `account:write`	bearerAuth or sessionCookie	idempotency-key	200 400 401 403 409 422 500
`GET` `/api/v1/me/devices` listClarkCantDevices	Linked ClarkCant installs (`devices:link` or `account:read`)	bearerAuth or sessionCookie	none	200 401 403 500
`DELETE` `/api/v1/me/devices/{id}` unlinkClarkCantDevice	Unlink a ClarkCant install (`devices:link` or `account:write`)	bearerAuth or sessionCookie	none	204 401 403 404 500
`GET` `/api/v1/me/oauth/grants` listOAuthGrants	OAuth clients the account has authorized	bearerAuth or sessionCookie	none	200 401 403 500
`DELETE` `/api/v1/me/oauth/grants/{id}` revokeOAuthGrant	Revoke an OAuth client's consent and tokens (id = client id)	bearerAuth or sessionCookie	none	204 401 403 404 500

publishers

Publisher organisations, members, verification and package claims

Operation	Summary	Auth	Headers	Responses
`GET` `/api/v1/me/publishers` listMyPublishers	Publishers the caller belongs to, with the caller's role	bearerAuth or sessionCookie	none	200 401 403 500
`POST` `/api/v1/me/publishers` createPublisher	Create a publisher (the caller becomes its owner)	bearerAuth or sessionCookie	idempotency-key	201 400 401 403 409 422 500
`GET` `/api/v1/me/publishers/{publisherId}/members` listPublisherMembers	Members of a publisher	bearerAuth or sessionCookie	none	200 401 403 404 500
`GET` `/api/v1/me/publishers/{publisherId}/invitations` listPublisherInvitations	Pending invitations (owners and admins)	bearerAuth or sessionCookie	none	200 401 403 404 500
`POST` `/api/v1/me/publishers/{publisherId}/invitations` inviteMember	Invite an email address; share the returned invitation id with the invitee (no email is sent)	bearerAuth or sessionCookie	idempotency-key	201 400 401 403 404 409 422 500
`POST` `/api/v1/me/invitations/{id}/accept` acceptInvitation	Accept an invitation addressed to the caller's email (the email must be verified)	bearerAuth or sessionCookie	idempotency-key	200 401 403 404 409 422 500
`GET` `/api/v1/me/publishers/{publisherId}/domains` listPublisherDomains	Claimed domains and their TXT challenge	bearerAuth or sessionCookie	none	200 401 403 404 500
`POST` `/api/v1/me/publishers/{publisherId}/domains` addPublisherDomain	Claim a domain; returns the DNS TXT record to publish	bearerAuth or sessionCookie	idempotency-key	201 400 401 403 404 409 422 500
`POST` `/api/v1/me/publishers/{publisherId}/domains/{childId}/verify` verifyPublisherDomain	Check the DNS TXT record now and mark the domain verified on a match	bearerAuth or sessionCookie	idempotency-key	200 401 403 404 409 422 500
`GET` `/api/v1/me/publishers/{publisherId}/repositories` listPublisherRepositories	Linked source repositories	bearerAuth or sessionCookie	none	200 401 403 404 500
`POST` `/api/v1/me/publishers/{publisherId}/repositories` linkPublisherRepository	Link a GitHub repository; returns the verification file to commit	bearerAuth or sessionCookie	idempotency-key	201 400 401 403 404 409 422 500
`POST` `/api/v1/me/publishers/{publisherId}/repositories/{childId}/verify` verifyPublisherRepository	Check the verification file on the default branch now	bearerAuth or sessionCookie	idempotency-key	200 401 403 404 409 422 500
`GET` `/api/v1/me/publishers/{publisherId}/claims` listPackageClaims	Package claims made by a publisher	bearerAuth or sessionCookie	none	200 401 403 404 500
`POST` `/api/v1/me/publishers/{publisherId}/claims` claimPackage	Claim an indexed package via npm maintainers or a verified repository; approved when proven	bearerAuth or sessionCookie	idempotency-key	201 400 401 403 404 409 422 500

publish

Package submissions: ask the marketplace to index an npm package version

Operation	Summary	Auth	Headers	Responses
`POST` `/api/v1/publish/submit` submitPackage	Ask the marketplace to index an npm package version (`packages:submit`)	optional	idempotency-key	202 400 401 403 409 422 500
`GET` `/api/v1/publish/submissions/{id}` getSubmission	Status of one submission (visible to its submitter and to curators)	optional	none	200 400 401 404 500

curation

Curator commands (packages:curate): curation status, featuring and collections

Operation	Summary	Auth	Headers	Responses
`POST` `/api/v1/curation/packages/{name}/status` setCurationStatus	Set a package's curation status (unreviewed, listed, featured, hidden, rejected)	optional	idempotency-key	200 400 401 403 404 409 422 500
`POST` `/api/v1/curation/packages/{name}/featured` featurePackage	Feature a package, or return a featured package to plain listing	optional	idempotency-key	200 400 401 403 404 409 422 500
`GET` `/api/v1/curation/collections/{slug}` getCollectionState	Admin view of a collection, including unpublished state and non-public items	optional	none	200 400 401 403 404 500
`POST` `/api/v1/curation/collections/{slug}` manageCollection	Run one collection command: create, update, add_item, remove_item or reorder	optional	idempotency-key	200 400 401 403 404 409 422 500