API reference

Everything the public API serves, in one table. The base URL is https://api.canverly.com for every route, and the site is always taken from the API key — there is no site parameter anywhere on this surface.

• Machine contract: /openapi.json (OpenAPI 3.1) · interactive viewer
• Agent contract: llms.txt
• Auth: Authorization: Bearer ck_…; the two read routes also accept a public pk_… key — see Keys, scopes & restrictions

Content

Method	Path	Scope	Page
GET	/v1/posts	posts:read	List posts
POST	/v1/posts	posts:write	Create a post
GET	/v1/posts/{reference}	posts:read	Get one post
PATCH	/v1/posts/{id}	posts:write	Update a post
GET	/v1/post-types	post_types:read	Post types

SEO

Method	Path	Scope	Page
GET	/v1/posts/{reference}/seo	seo:read	Post SEO
PATCH	/v1/posts/{reference}/seo	seo:write	Post SEO
GET	/v1/sites/me/seo	seo:read	Site SEO
PATCH	/v1/sites/me/seo	seo:write	Site SEO

Media

Method	Path	Scope	Page
GET	/v1/media	media:read	Media
POST	/v1/media	media:write	Media
GET	/v1/media/{id}	media:read	Media
DELETE	/v1/media/{id}	media:write	Media

Site

Method	Path	Scope	Page
GET	/v1/sites/me	sites:read	Site info
GET	/v1/sites/me/settings	site:read	Site settings
PATCH	/v1/sites/me/settings	site:write	Site settings

Note

sites:read (the GET /v1/sites/me identity call) and site:read / site:write (the settings blob) are different scopes, and the singular/plural is not a typo. A key that can read the site’s domain cannot necessarily read its settings.

Audience & data

Method	Path	Scope	Page
GET	/v1/analytics/summary	analytics:read	Analytics
GET	/v1/analytics/posts	analytics:read	Analytics
GET	/v1/leads	leads:read	Leads
GET	/v1/leads/{id}	leads:read	Leads
GET	/v1/export	export (+ leads:read / analytics:read)	Bulk export & import
POST	/v1/import	import + posts:write	Bulk export & import

Key management

POST, GET /admin/api-keys and PATCH, DELETE /admin/api-keys/{id} also exist, but they are not part of the integrator surface: they authenticate with a site-owner browser session, not with a ck_ key. See Keys, scopes & restrictions.

Conventions that hold everywhere

• The key fixes the site. site_id, org_id and author_id are never read from a URL, query or body. Sending them changes nothing.
• 404, not 403, for other tenants. A resource that belongs to another site is indistinguishable from one that does not exist. This is deliberate: a 403 would confirm that someone else’s draft, lead or asset exists.
• Limits are never silently clamped. A limit outside its documented range is a 400 with the range in the message, not a quietly truncated page.
• One error envelope: { "error": { "code": …, "message": … } }. See Errors & rate limits.