# Canverly Public API

> Public REST API for a Canverly site: publish and edit posts, read the public
> archive, upload media, set SEO, change site settings, read analytics and form
> leads, and move content in and out in bulk. Any tool, automation or AI agent
> can use it. JSON over HTTPS. Authentication is a per-site API key
> (`Authorization: Bearer ck_...`). The site is fixed by the key — a key can only
> ever touch its own site. Post bodies are a block document (`blocks_json`), not
> raw HTML. This file contains everything an agent needs.

Base URL: https://api.canverly.com
OpenAPI: https://api.canverly.com/openapi.json  (served by the API)
Contract: https://developers.canverly.com/specs/content-openapi.yaml  (version 1.0.0, 24 operations under /v1)
Docs: https://developers.canverly.com/en/  (pt-BR: https://developers.canverly.com/)
Max request body: 4 MiB JSON (8 MiB for media upload and NDJSON import)

## Authentication

Send on every request:
  Authorization: Bearer ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Two key classes:
- ck_  secret key. Server-side only. Can write. Required by every route except
       the two public read routes, which also accept pk_.
- pk_  public read key. Read-only, one site, only from origins the owner
       registered. May be sent as ?key=pk_... (avoids a CORS preflight).
       Reaches ONLY GET /v1/posts and GET /v1/posts/{reference}; every other
       route answers 401 to a pk_ key. A ck_ key in ?key= is a 400.

Keys are created in the admin (Configurações → Integrações API) and shown once.
No API key can create, list or revoke a key — key management is a site-owner
browser session, not an API surface.

Scopes are opt-in per key. The full list:
  posts:write posts:read post_types:read sites:read
  site:read site:write seo:read seo:write media:read media:write
  analytics:read leads:read export import
Note: sites:read (identity) and site:read (settings blob) are DIFFERENT scopes.

A key may also carry per-request restrictions, all fail-closed: IP/CIDR
allowlist, country allowlist (GeoIP; an indeterminate country DENIES), a time
window in an IANA zone, and — for pk_ — an origin allowlist. A violation is 403
naming the dimension, e.g. "request blocked by this key's IP restriction".

## Rate limits

- 60 req/min per key .......... every route except the two public read routes
- 600 req/min per key ......... GET /v1/posts, GET /v1/posts/{reference}
- 60 req/min per (key, IP) .... the same two routes, pk_ keys only
- 10 req/min per key .......... /v1/leads, /v1/leads/{id}, export of leads
                                (layered ON TOP of the 60/min bucket)
429 carries Retry-After (seconds). A request refused by a key restriction costs
no quota.

## Endpoint: POST /v1/posts  (scope: posts:write)

Create a post; publish immediately with status "published".

Optional header: Idempotency-Key: <stable id, <=255 chars>
  A replay with the same key AND body returns the original 201
  (with header Idempotency-Replayed: true) and creates no duplicate.
  Cached 24h, scoped per api key. Errors cache nothing (safe to retry).

Request body (application/json):
- title          string   REQUIRED
- blocks_json    object   REQUIRED  { "v": 1, "blocks": Block[] }
- status         string   optional  "draft" (default) | "published"
- slug           string   optional  auto from title; send a stable slug for safe retries
- excerpt        string   optional  stored as SEO description
- language       string   optional  BCP-47, default "pt-BR"
- post_type      string   optional  "post" (default) | "page" | custom slug
- category_slugs string[] optional
- tag_slugs      string[] optional

Never send site_id / org_id / author_id — they are bound to the key and ignored.

Block (each needs a unique non-empty "id"):
- { "id":"p1", "type":"paragraph", "text":"inline HTML: <a>,<strong>,<em>,<code>,<br>" }
- { "id":"h1", "type":"heading", "attrs":{"level":2}, "text":"Heading" }   (level 2–6)
- { "id":"l1", "type":"list", "attrs":{"style":"unordered"}, "text":"item1\nitem2" }  (style: "unordered"|"ordered"; or attrs.items[]+attrs.ordered)
- { "id":"c1", "type":"code", "attrs":{"language":"python"}, "text":"verbatim code" }
- { "id":"q1", "type":"quote", "text":"A quote." }
- { "id":"i1", "type":"image", "attrs":{"src":"https://.../x.jpg","alt":"..."} }

HTML in block text is allowlist-sanitized: <script>, on* handlers, javascript: URLs
and <iframe> are stripped; formatting tags and http/https/mailto links are kept.

Response 201:
  { "id": "<ULID>", "slug": "<slug>", "status": "published|draft", "public_url": null }
The post is then live at https://<site primary_domain>/<slug>.

Minimal valid request:
  curl -X POST https://api.canverly.com/v1/posts \
    -H "Authorization: Bearer ck_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{"title":"Example","status":"published","blocks_json":{"v":1,"blocks":[{"id":"p1","type":"paragraph","text":"Body."}]}}'

## Endpoint: GET /v1/posts  (scope: posts:read)

Paginated PUBLIC archive of the key's site. Drafts, future-dated posts and
access-restricted posts are never returned.

Query: limit (1..50, default 20; out of range = 400, never clamped),
       cursor (opaque, from the previous page's next_cursor; invalid = 400),
       category (slug; comma-separated = match ANY), tag (same),
       q (full-text over title and excerpt),
       since (RFC-3339; returns updated_at >= since — the incremental sync hook),
       language (BCP-47), key (a pk_ key, browser callers only).
Header: If-None-Match -> 304 with no body when the ETag matches.
Cache-Control: public, max-age=60, stale-while-revalidate=300.

Response 200:
  { "items": [PublicPost], "next_cursor": string|null }
next_cursor absent or null = end of the archive. There is no total, no has_more.
Pagination is keyset over (published_at, id), never OFFSET, so pages stay stable
while new posts are published.

PublicPost: id (26-char Crockford ULID), slug, title, excerpt, published_at,
updated_at, author ({name, slug, avatar_url} or NULL — handle null), categories[]
and tags[] ({slug, name}; name is never empty — an unregistered slug is
humanized), cover_url (string|null), url (canonical public URL, already carrying
the language prefix when needed), reading_time (minutes, max(1, ceil(words/200))),
language, post_type. The BODY is not in the listing — use the detail route.

## Endpoint: GET /v1/posts/{reference}  (scope: posts:read)

reference = ULID (26 chars), UUID (36 chars) or slug. Anything not id-shaped is
treated as a slug. Same public gate as the listing.
Cache-Control: public, max-age=300, stale-while-revalidate=600. If-None-Match works.

Response 200: every PublicPost field plus content_html — rendered and
allowlist-sanitized on the way out. No <script>, <iframe>, <form>, no event
attributes. Ad blocks, product cards and story pages are OMITTED; video embeds
become a link; an image stored as a library id comes out with its URL resolved,
and is omitted entirely when the asset is gone (never a broken <img>).

404 covers all of: no such post, a draft, a future-dated post, an
access-restricted post, and a post on another site. This is deliberate — a 403
would confirm that someone else's draft exists.

## Endpoint: PATCH /v1/posts/{id}  (scope: posts:write)

Partial patch; only the fields you send change. Body (all optional):
  title, blocks_json, excerpt, category_slugs, tag_slugs, published_at (RFC3339).
There is NO status and NO slug field: you cannot publish a draft, unpublish, or
rename a URL through this route.
Empty patch = 400 "no updatable fields provided". Another site's id = 404.
Response 200 = the full stored post record (internal shape, not PublicPost).

TRAPS:
- excerpt/category_slugs/tag_slugs are stored INSIDE the post's SEO object, and
  that object is REPLACED, not merged. A patch carrying only category_slugs
  clears the post's SEO title, description, og_image, canonical_url, no_index,
  schema_type and tag_slugs. Use the SEO route instead when the post has SEO.
- published_at re-pings IndexNow on EVERY call. Send it only when the date is
  actually wrong.

## Endpoint: GET /v1/post-types  (scope: post_types:read)

Returns { "items": [ { "slug", "name", "plural_name", "is_default", "public",
"hierarchical", "has_archive", "id" } ] }. Use "slug" as post_type on
POST /v1/posts. "post" and "page" always exist.

## Endpoint: GET /v1/sites/me  (scope: sites:read)

Returns { "id", "slug", "primary_domain", "default_language" } for the key's site.
Use primary_domain to build the public URL for verification. Cache it.

## Endpoints: site settings  (scopes: site:read / site:write)

GET  /v1/sites/me/settings
PATCH /v1/sites/me/settings

GET returns a projection: id, slug, primary_domain, aliases (all read-only),
theme_id, default_language, enabled_languages, multi_lang_enabled, prefer_www,
force_redirect, child_redirect_mode, redirect_status_code, and the settings blob.

PATCH writes only allowlisted fields:
- top level: theme_id, default_language, enabled_languages, multi_lang_enabled,
  prefer_www, force_redirect, child_redirect_mode, redirect_status_code (replaced)
- settings.*: social, footer_columns, legal_links, search, customization,
  advanced, subscriptions_enabled, language_url_mode (MERGED over what is stored)
Excluded on purpose: code_injection, ads, modals, applets, integrations, seo
(seo has its own route). org_id/status/site_id/slug/primary_domain/aliases are
ignored, not rejected. A body with nothing writable = 400.

## Endpoints: SEO  (scopes: seo:read / seo:write)

GET   /v1/posts/{reference}/seo     reference must be the post ID (not a slug)
PATCH /v1/posts/{reference}/seo
GET   /v1/sites/me/seo
PATCH /v1/sites/me/seo

Body may be { "seo": {...} } or the bare fields; GET always answers wrapped as
{ "seo": {...} }, empty object when unset.

Post keys: title, description, og_image, twitter_card, no_index, canonical_url,
schema_type (Article|BlogPosting|NewsArticle), category_slugs, tag_slugs.
  WARNING: the post SEO patch REPLACES the object. Read it, modify it, send the
  whole thing back. Omitted keys are cleared.
  schema_type "NewsArticle" also opts the post into the Google News sitemap.

Site keys: title_template, default_title, default_description, default_og_image,
twitter_card, twitter_handle, robots.
  Site SEO IS merged — omitted keys keep their value.

A body with no allowlisted key = 400 listing the accepted keys.

## Endpoints: media  (scopes: media:read / media:write)

GET    /v1/media          limit (1..500, default 100; out of range = 400),
                          folder_id, tag_id -> { "items": [MediaAsset] }
POST   /v1/media          multipart/form-data with a part named `file`.
                          Body cap 8 MiB (413). Returns 202 with the asset;
                          variants are generated asynchronously, so it comes
                          back status "processing" and becomes "ready" later.
GET    /v1/media/{id}     another site's id -> 404
DELETE /v1/media/{id}     soft delete -> 204

MediaAsset: id, key, mime, bytes, width|null, height|null, alt_text|null, hash,
status ("processing"|"ready"), original_url|null.

## Endpoints: analytics  (scope: analytics:read)

GET /v1/analytics/summary   from, to (YYYY-MM-DD, UTC, to inclusive) take
                            precedence; otherwise days (1..365, default 30).
  -> { from, to, days, totals: {views, visitors, sessions},
       timeseries: [{date, views, visitors}], top_paths: [{key, views}] }
GET /v1/analytics/posts     same window params + limit (1..200, default 50;
                            out of range = 400) and offset (default 0).
  -> { items: [{path, views}], total, limit, offset }

/v1/analytics/posts is a projection of the summary's top_paths, paginated at the
edge — the unit is a URL PATH, not a post id, and the upstream top_paths list is
short, so it is not a full per-post census of the site.

Data is first-party, cookieless and bot-filtered. Trust the echoed from/to/days:
an unparseable window value falls back to the 30-day preset rather than erroring.

## Endpoints: leads  (scope: leads:read)

GET /v1/leads       form_id, status (clean default | spam | all), de (period
                    start), ate (period end), cursor, limit (1..200, default 50),
                    ordem (desc default | asc)
  -> { "items": [Lead], "next_cursor": string|null }  (empty string also = end)
GET /v1/leads/{id}  one lead, same shape as a list item

Lead: id, form_id, page_path, data (field id -> value), status (clean|spam),
spam_score, created_at.

LEADS ARE PERSONAL DATA. leads:read is opt-in and never granted by default;
every read is written to the audit trail with the API key as the actor; the
10 req/min bucket applies on top of the general one. 404 means any of: not this
site's lead, no such lead, or the Forms app is not installed — deliberately
indistinguishable. 422 means an invalid filter.

## Endpoints: bulk  (scopes: export / import)

GET /v1/export?resource=posts|leads|analytics&format=ndjson|csv
  - format defaults to ndjson. posts + csv = 400 (block bodies do not flatten).
  - leads also requires leads:read; analytics also requires analytics:read.
  - leads filters: form_id, status, de, ate. analytics filters: from, to, days.
  - streams with Content-Disposition: attachment. NDJSON = one object per line.

POST /v1/import?resource=posts  (default and only value)
  - Content-Type: application/x-ndjson, one line = one post, each line using the
    SAME body schema as POST /v1/posts.
  - Requires BOTH import AND posts:write.
  - Caps: 8 MiB body (413) and 1000 lines (400). Empty/non-UTF-8 body = 400.
  - Idempotent per line content: a line already seen returns status "replayed".
  - Response 200: { "created": int, "failed": int, "results": [ { "line",
    "status": "created"|"replayed"|"error", "id"?, "slug"?, "post_status"?,
    "error"? } ] }
  - A bad line does NOT abort the import. A 200 CAN contain failures — always
    inspect "failed" and the per-line results, never just the status code.

## Errors

Envelope: { "error": { "code": "...", "message": "..." } }
(Body-parse errors from the framework — malformed JSON, wrong type, missing
Content-Type — return the status with a short plain-text message instead; branch
on the status code, not on the body shape.)

- 304               If-None-Match matched; no body
- 400 bad_request   malformed JSON, empty title, bad limit/cursor/format,
                    empty patch, ck_ key in ?key=
- 401 unauthorized  missing/invalid/revoked key, or a pk_ key on a ck_-only route
- 403 forbidden     scope not granted; or blocked by the key's IP/region/time
                    restriction; or a pk_ key from an unregistered origin
- 404 not_found     not on this site, or does not exist — indistinguishable
- 413               body over the route's cap
- 415               missing/incorrect Content-Type
- 422 unprocessable missing blocks_json / wrong field type / invalid filter /
                    legacy key (re-create it)
- 429 rate_limited  honor Retry-After
- 5xx upstream      transient; retry with backoff

## Rules for agents

1. Post bodies are blocks_json — NOT raw HTML, NOT markdown.
2. Do not send site_id/org_id/author_id anywhere. They are ignored.
3. For safe retries on create, send Idempotency-Key: <stable id> (e.g. the source
   item id); a replay with the same key+body returns the original 201.
4. On 429, sleep Retry-After seconds then retry; on 5xx, exponential backoff
   (max ~3), reusing the same Idempotency-Key. On 404, stop — do not enumerate ids.
5. To go live use status "published"; otherwise it stays a draft.
6. Before publishing, consider GET /v1/posts?q=<title> to avoid a duplicate, and
   PATCH the existing post instead.
7. Never guess whether a scope is granted — a 403 names the missing scope.
8. Read the SEO object before patching it: the post-level patch REPLACES it.

## Full reference

- Overview: https://developers.canverly.com/en/apis/content/
- All endpoints: https://developers.canverly.com/en/reference/content/
- Authentication: https://developers.canverly.com/en/getting-started/authentication/
- Keys, scopes & restrictions: https://developers.canverly.com/en/getting-started/keys/
- Publishing guide: https://developers.canverly.com/en/apis/content/publishing/
- Content blocks: https://developers.canverly.com/en/apis/content/blocks/
- List & read posts: https://developers.canverly.com/en/reference/content/posts-read/
- Update a post: https://developers.canverly.com/en/reference/content/posts-update/
- SEO: https://developers.canverly.com/en/reference/content/seo/
- Media: https://developers.canverly.com/en/reference/content/media/
- Site settings: https://developers.canverly.com/en/reference/content/site-settings/
- Analytics: https://developers.canverly.com/en/reference/content/analytics/
- Leads: https://developers.canverly.com/en/reference/content/leads/
- Bulk export & import: https://developers.canverly.com/en/reference/content/bulk/
- Errors & rate limits: https://developers.canverly.com/en/getting-started/errors-and-limits/
- Agent guide: https://developers.canverly.com/en/ai-agents/
- OpenAPI JSON: https://api.canverly.com/openapi.json
- Webhooks (form leads, HMAC-signed): https://developers.canverly.com/en/apis/webhooks/
- Embeddable widget: https://developers.canverly.com/en/apis/widget/
- OpenAPI by service (generated): https://developers.canverly.com/en/reference/
- Published specs: https://developers.canverly.com/specs/content-openapi.yaml
- Public forms (how submissions and leads work): https://developers.canverly.com/en/apis/forms/
- Headless (your own front end on the read API): https://developers.canverly.com/en/themes/headless/
- Changelog and versioning policy (N-1): https://developers.canverly.com/en/changelog/
- Changelog of the content API (generated): https://developers.canverly.com/en/changelog/api/
- Portal home (pt-BR): https://developers.canverly.com/