Chart Builder REST API

Custom REST routes under the prc-chart-builder/v1 namespace. Use Application Passwords or cookie auth as appropriate for the capability on each route.

Base path: /wp-json/prc-chart-builder/v1/

Auth summary

Route index

Not REST: plugins/prc-chart-builder/includes/class-chart-export-endpoint.php serves permalink /chart/{slug}/export/ via template_redirect, not register_rest_route.

GET /charts/{id}/data.csv

Public download of table data for Dataset JSON-LD and the chart data download UI.

Permission: __return_true. The callback still rejects unpublished charts and charts with allow_data_download disabled.

Success: HTTP 200 with raw CSV body (not JSON). Served through rest_pre_serve_request with:

• Content-Type: text/csv; charset=utf-8
• Content-Disposition: attachment; filename="{slug}_data_{Y-m-d}.csv"
• UTF-8 BOM prefix
• Cache-Control: public, max-age=86400

Errors:

Source: includes/class-json-ld.php

GET /chart-patterns

Cached pattern library index for the chart creation wizard.

Permission: edit_posts

Success (200):

{
	"patterns": [
		{ "id": 0, "title": "", "excerpt": "", "typeSlug": "", "content": "" }
	],
	"counts": {},
	"version": ""
}

Source: includes/class-chart-patterns-endpoint.php

GET / POST /creation-ui

Site rollout flag for the guided chart creation UI.

Permission: manage_options

GET success (200): { "enabled": true }

POST body: JSON object with boolean enabled.

POST errors: invalid_creation_ui_setting (400)

Source: includes/settings/class-creation-ui-settings.php

GET / POST /screenshot-settings

Site-level screenshot provider pin and capture defaults (selector, delay, scale, padding, fallback chart size). Stored in prc_chart_builder_screenshot_settings, not in the portable chart theme.

Permission: manage_options

GET success (200):

{
	"settings": {
		"provider": "",
		"selector": ".wp-chart-builder-chart",
		"delay_seconds": 5,
		"device_scale_factor": 2,
		"viewport_side_padding": 48,
		"default_chart_width": 640,
		"default_chart_height": 400
	},
	"defaults": {},
	"providers": [
		{
			"slug": "screenshotone",
			"label": "ScreenshotOne",
			"configured": true,
			"constants": [
				{ "name": "PRC_PLATFORM_SCREENSHOTONE_ACCESS_KEY", "set": true },
				{ "name": "PRC_PLATFORM_SCREENSHOTONE_SECRET_KEY", "set": true }
			]
		}
	],
	"resolved_provider": "screenshotone",
	"provider_locked": false,
	"locked_provider": ""
}

providers[].constants lists variable names and whether each is defined and non-empty. Values are never included.

POST body: JSON object of settings fields, or { "settings": { ... } }. When PRC_PLATFORM_CHART_SCREENSHOT_PROVIDER is set, provider is ignored.

POST errors: invalid_screenshot_settings (400)

Source: includes/settings/class-screenshot-settings.php

GET / POST /theme

Read or persist the per-site chart theme. POST also purges edge cache for theme delivery.

Permission: manage_options

Success (200): active theme object from Settings::get_active_theme() (keys such as config and palettes; empty array when unset).

POST errors (400): invalid_theme_payload, invalid_theme_key, invalid_theme_config, invalid_theme_palettes

Source: includes/settings/class-theme-rest-controller.php

POST /import-pch

Convert a PCH JSON document into a draft chart CPT and return its ID.

Permission: edit_posts

Body: full PCH JSON object (Content-Type: application/json). Required checks in the callback:

• Non-empty object
• $schema must be prc-chart-handoff/v1
• chartType required
• data.values required non-empty array

Content-Type: application/jsonAuthorization: Bearer <token>

{
  "$schema": "prc-chart-handoff/v1",
  "version": "1.0.0",
  "chartType": "bar",
  "data": {
    "values": [{ "x": "A", "y": 1 }],
    "xColumn": "x",
    "yColumn": "y"
  },
  "metadata": { "title": "Example" }
}

{
  "post_id": 123,
  "edit_url": "https://example.com/wp-admin/post.php?post=123&action=edit",
  "warnings": []
}

Errors: pch_empty, pch_unsupported_schema, pch_missing_chart_type, pch_missing_data (400). Insert failures return the wp_insert_post error.

Full schema and chart-type mapping: Chart Handoff README

Source: includes/chart-handoff/class-pch-import-endpoint.php

GET /chart/{id}/referencing-posts

Posts that reference a chart (synced-chart embeds) for the inspector sidebar.

Permission: edit_posts

Success (200): array of { id, title, type, status, edit_url, permalink, date, modified }, or []

Error: invalid_chart (404)

Source: includes/inspector-sidebar-panel/class-inspector-sidebar-panel.php

POST /chart/{id}/regenerate-png

Clear _chart_attributes_hash and enqueue an Action Scheduler job to capture a static PNG.

Permission: edit_posts

Success (200): { "scheduled": true, "post_id": 123 } (scheduled is false when a job was already pending)

Errors:

Source: includes/class-png-export.php

POST /ai/generate

Generate chart block markup from description, CSV, and/or image. Registered only when the Chart AI Create experiment is enabled.

Permission: edit_posts

Success wrapper: HTTP 200 with { "content": "<block markup>", "error": "" }. Generation failures still return HTTP 200 with error set and empty content.

Same contract as the Abilities API ability prc-chart-builder/generate. See abilities.md.

Source: includes/ai-experiment/class-chart-ai-ability.php

Related docs

• Abilities
• Architecture
• Plugin docs landing page
• Chart Handoff README
• AI experiment README