REST API

All routes are registered in includes/class-coverkit-rest.php on namespace coverkit/v1.

Base URL:

/wp-json/coverkit/v1

Routes

Method	Route	Callback	Permission
GET	/template[/{template_id}]	REST::handle_template()	edit_posts
POST	/clear-cache	REST::clear_cache()	edit_posts
GET	/screenshot	REST::get_screenshot()	edit_posts
POST	/preview	REST::generate_preview()	Use-case mode: edit_post for template_id. Canvas mode: edit_post for post_id
GET	/autocompleters	REST::get_autocompleters()	public
GET	/canvas/{filename}	REST::serve_canvas_image()	public
GET	/use-cases	REST::get_use_cases()	edit_posts
GET	/binding-fields	REST::get_binding_fields()	edit_posts
GET	/template/{template_id}/preview.{extension}	REST::get_template_preview_image()	edit_post for template_id
GET	/use-case/{use_case}/{template_id}/{post_id}.{extension}	REST::get_use_case_image()	Public when the use case type is marked public (for example featured_image, opengraph); otherwise edit_post when post_id > 0, else edit_posts
GET	/featured-image/preview/{post_id}	REST::get_featured_image_editor_preview()	edit_post for post_id
GET	/fonts/uploaded	REST::get_uploaded_fonts()	upload_files
POST	/fonts/uploaded	REST::upload_uploaded_font()	upload_files (multipart file)
DELETE	/fonts/uploaded/{slug}	REST::delete_uploaded_font()	upload_files

Template preview (editor/admin list)

GET /wp-json/coverkit/v1/template/{template_id}/preview.png?width=300
GET /wp-json/coverkit/v1/template/{template_id}/preview.png?reload=1
GET /wp-json/coverkit/v1/template/{template_id}/preview.png?post_id=456&width=300

Canvas layout preview (not a registered use case). Optional width (responsive sizes), reload=1 (force regenerate), post_id (mapped field data). Requires edit_post for the template. Helper: coverkit_rest_template_preview_url() in includes/functions.php. On-disk cache (under get_coverkit_path()): cache/coverkit-{id}/coverkit/{template_id}-{width}.png or cache/coverkit-{id}/post/{post_id}/{template_id}-template-preview-{width}.png, where {id} is from coverkit_get_cache_unique_id(). Post-bound use-case outputs use cache/coverkit-{id}/{post_type}/{post_id}/{template_id}-{use_case}.{ext} (e.g. 5748-opengraph.png). Public URLs remain REST routes, not direct cache paths.

Template payload

GET /wp-json/coverkit/v1/template?context_type=post&context_id=123

Requires edit_posts. Returns a minimal template summary (id, title, status, width, height, preview_url) — not full post_content. Requires context_type; optional context_id and template_id route segment.

Live preview (editor)

POST /wp-json/coverkit/v1/preview

Single endpoint for live editor previews. The handler branches on use_case:

Mode	When	Required body fields	Generation
Use case	use_case is a registered slug (not template_preview)	use_case, template_id, content, assignment	Renderer::generate( $use_case, … ) with editor_preview_uncropped
Canvas	Omit use_case, or send use_case: template_preview	content, post_id (editor post being edited)	Renderer::generate_from_content()

Shared optional params: format, width, quality. Canvas mode also supports meta (wraps content in a coverkit/canvas block), template_id, and save_to_uploads (persist to the media library for transforms).

Example — use case sidebar preview:

{
  "use_case": "opengraph",
  "template_id": 123,
  "post_id": 0,
  "content": "<!-- wp:coverkit/layer ... -->",
  "assignment": {
    "active": true,
    "settings": {},
    "mappings": {}
  }
}

Example — layer/canvas preview:

{
  "content": "<!-- wp:coverkit/layer ... -->",
  "post_id": 123,
  "meta": { "width": 1200, "height": 630, "background": "#ffffff" }
}

Response (minimum): url, width, height. Canvas mode may also include data (full generator payload), id, and saved_to_uploads when saving to uploads.

Editor clients: src/util/previewRequest.js (fetchUseCasePreview, fetchCanvasPreview).

Block bindings field catalog (editor)

GET /wp-json/coverkit/v1/binding-fields
GET /wp-json/coverkit/v1/binding-fields?use_case=sandbox

Requires edit_posts. Returns mapping sources formatted for WordPress native block bindings getFieldsList() (label, args.field, type). Defaults to the sandbox use case when use_case is omitted.

{
  "use_case": "sandbox",
  "fields": [
    {
      "label": "Post title",
      "args": { "field": "post_title" },
      "type": "string"
    }
  ]
}

Use case registry (editor)

GET /wp-json/coverkit/v1/use-cases
GET /wp-json/coverkit/v1/use-cases?template_id=123

Optional query template_id — current CoverKit template post ID in the editor. When a use case has single: true and template_id is provided, the response includes single_holder: null when no other template holds the active slot, or { "id": 42, "title": "Admin branding" } when another template is already active (used for editor conflict warnings).

Response envelope:

{
  "use_cases": {
    "opengraph": {
      "slug": "opengraph",
      "label": "Open Graph image",
      "description": "...",
      "single": false,
      "supports": [],
      "settings_schema": {},
      "recommended_settings": { "dimensions": { "width": 1200, "height": 630 } },
      "output_profile": { "crop": false, "dimensions": { "width": 1200, "height": 630 } },
      "mapping_sources": { "post_title": { "required": true } }
    },
    "dashboard_widget": {
      "slug": "dashboard_widget",
      "label": "Dashboard widget",
      "single": true,
      "single_holder": null
    }
  }
}

Use case image

GET /wp-json/coverkit/v1/use-case/opengraph/123/456.png
GET /wp-json/coverkit/v1/use-case/sandbox/123/456.png?reload=1
GET /wp-json/coverkit/v1/use-case/featured_image/123/456.jpg?featured_image_id=99

Streams generated bytes after Renderer::generate( $use_case, $template_id, $post_id, $options ).

Types registered with 'public' => true (for example opengraph and featured_image in includes/use-cases/bootstrap.php) allow anonymous access for published, viewable posts only (Field_Resolver::can_collect_for_post()). Draft, private, and password-protected posts return 404 for anonymous callers. Override with coverkit_use_case_public_image_permission.

Open Graph og:image meta uses coverkit_rest_use_case_image_url( 'opengraph', … ) (no REST nonce) so social crawlers can fetch the image without authentication.

Optional query featured_image_id — current featured media ID from the block editor (logged-in preview); used by featured_image so Remove/Replace updates before save when a valid REST nonce is present.

Featured image editor preview (block editor Summary)

GET /wp-json/coverkit/v1/featured-image/preview/456?template_id=123&featured_image_id=99

Requires edit_post for post_id. Returns JSON:

{
  "enabled": true,
  "template_id": 123,
  "url": "https://example.com/wp-json/coverkit/v1/use-case/featured_image/123/456.jpg",
  "width": 1200,
  "height": 630
}

When no eligible template or the use case is not booted, enabled is false and url is null. Optional template_id forces a CoverKit template (template editor). Optional featured_image_id passes the unsaved featured media from the post editor.

Autocompleters

GET /wp-json/coverkit/v1/autocompleters

Returns tag/label pairs for shape text tokens; extend with coverkit_autocompleter_options.

Canvas cache

GET /wp-json/coverkit/v1/canvas/{hash}.png
GET /wp-json/coverkit/v1/canvas/{hash}-600x315.png

Serves files from _cache/generator/. Resized widths must be in get_coverkit_responsive_sizes() (default: 100, 300, 400, 600, 800, 1200, 1920). Cache-Control max-age from coverkit_canvas_image_cache_time (default one year). Canvas block images always use ETag / Last-Modified / 304 (default one-year max-age).

Browser cache on other image GET routes

Route	Browser cache (ETag / 304 / Cache-Control)
GET /template/{id}/preview.png	Never — always nocache_headers() (admin list, sidebar, popovers)
GET /use-case/{slug}/...	Only for public use cases requested without _wpnonce, editor field overrides, featured-image override, or reload=1 (e.g. Open Graph meta, front-end featured image)
GET /canvas/{hash}.png	Always (see above)

Editor and admin use-case preview URLs from coverkit_rest_use_case_image_url() include _wpnonce by default and therefore stay uncached. Filter: coverkit_allow_image_browser_cache.

Screenshot

GET /wp-json/coverkit/v1/screenshot?url=https://example.com&width=1200&height=630

Requires edit_posts. URL is validated to reduce SSRF risk. Note: route args are registered as width / height / viewport_width / viewport_height, but get_screenshot() reads screenshotWidth, screenshotHeight, viewportWidth, viewportHeight — pass those names until the route args are aligned.

Uploaded fonts (editor)

GET    /wp-json/coverkit/v1/fonts/uploaded
POST   /wp-json/coverkit/v1/fonts/uploaded   (multipart field: file — TTF or OTF)
DELETE /wp-json/coverkit/v1/fonts/uploaded/{slug}

Requires upload_files. Files are stored under wp-content/uploads/fonts/coverkit/. Listing and upload use the Font Family picker in the template editor; local uploads override Google fonts when the slug matches.

Async generation

Action coverkit_generate_image processes queued URLs stored in option coverkit_generate_image (see REST::handle_generate_image()).