craft-cms-skills

Important: Use this plugin, Not YAML Files

CRITICAL: Always use this HTTP API to manage Craft CMS content. Never directly modify YAML configuration files in the config/project/ directory. The API ensures proper validation, maintains data integrity, and handles all necessary relationships automatically. Direct YAML edits can corrupt your Craft installation.

CRITICAL: The skills plugin must be installed to Craft. You can verify installation by running php craft plugin/list and install it with php craft plugin/install skills

Base URL Configuration

All API routes require a base URL and API prefix. The standard Craft CMS configuration uses the PRIMARY_SITE_URL environment variable and a configurable API prefix:

• Environment Variable: Check for PRIMARY_SITE_URL in ENV or .env file
• If Not Set: Ask the user for the base URL to use
• API Prefix: Configurable prefix that defaults to /api
  • Check Order:
    1. First check config/skills.php for apiPrefix in the PHP array
    2. If not found, try the default /api
    3. If requests fail, ask the user for the configured API prefix
• Route Format: {PRIMARY_SITE_URL}/{apiPrefix}/{endpoint}
• Default Example: https://craft-site.com/api/sections
• Custom Prefix Example: https://craft-site.com/custom-api/sections

Request/Response Format

All API endpoints:

• Return JSON: All responses are in JSON format with structured data
• Accept Header: Include Accept: application/json header in requests to ensure errors are also formatted as JSON for better error handling and debugging
• Content-Type: Use Content-Type: application/json for POST/PUT requests with JSON body data

Content

• create_entry - POST /api/entries - Create entries with section/entry type IDs and field data
• get_entry - GET /api/entries/<id> - Retrieve entry by ID with all fields and metadata
• update_entry - PUT /api/entries/<id> - Update entry (prefers draft workflow)
• delete_entry - DELETE /api/entries/<id> - Delete entry (soft/permanent)
• search_content - GET /api/entries/search - Search/filter entries by section/status/query

Drafts

• create_draft - POST /api/drafts - Create draft from scratch or existing entry
• update_draft - PUT /api/drafts/<id> - Update draft content/metadata (PATCH semantics)
• apply_draft - POST /api/drafts/<id>/apply - Publish draft to canonical entry

Sections

• create_section - POST /api/sections - Create section with types/versioning/sites
• get_sections - GET /api/sections - List all or filter by IDs
• update_section - PUT /api/sections/<id> - Update properties/settings
• delete_section - DELETE /api/sections/<id> - Permanently delete (removes all entries)

Entry Types

• create_entry_type - POST /api/entry-types - Create with handle/name/layout
• get_entry_types - GET /api/entry-types - List with fields/usage/URLs
• update_entry_type - PUT /api/entry-types/<id> - Update properties/layout
• delete_entry_type - DELETE /api/entry-types/<id> - Delete if not in use

Fields

• create_field - POST /api/fields - Create with type and settings
• get_fields - GET /api/fields - List global or layout-specific
• get_field_types - GET /api/fields/types - List available types
• update_field - PUT /api/fields/<id> - Update properties/settings
• delete_field - DELETE /api/fields/<id> - Permanently delete (removes data)

Field Layouts

• create_field_layout - POST /api/field-layouts - Create empty field layout for entry types
• get_field_layout - GET /api/field-layouts - Get field layout structure by entry type/layout/element ID
• add_tab_to_field_layout - POST /api/field-layouts/<id>/tabs - Add tab to field layout with flexible positioning (prepend/append/before/after)
• add_field_to_field_layout - POST /api/field-layouts/<id>/fields - Add custom field to tab with positioning, width, required, and display options
• add_ui_element_to_field_layout - POST /api/field-layouts/<id>/ui-elements - Add UI elements (heading, tip, horizontal rule, markdown, template) to layouts
• move_element_in_field_layout - PUT /api/field-layouts/<id>/elements - Move fields/UI elements within or between tabs with precise positioning
• remove_element_from_field_layout - DELETE /api/field-layouts/<id>/elements - Remove fields or UI elements from field layout

Sites

• get_sites - GET /api/sites - List all sites with IDs/handles/URLs

Assets

• create_asset - POST /api/assets - Upload file from local/remote URL to volume
• update_asset - PUT /api/assets/<id> - Update metadata or replace file
• delete_asset - DELETE /api/assets/<id> - Delete asset and file
• get_volumes - GET /api/volumes - List asset volumes with IDs/URLs

Addresses

• get_addresses - GET /api/addresses - List/search addresses by owner, field, and location
• get_address - GET /api/addresses/<id> - Retrieve address details with owner and field context
• create_address - POST /api/addresses - Create generic owner-backed addresses for users or custom address fields
• update_address - PUT /api/addresses/<id> - Update address attributes and custom fields
• delete_address - DELETE /api/addresses/<id> - Delete address (soft/permanent)
• get_address_field_layout - GET /api/addresses/field-layout - Retrieve the single global address field layout

Users

• get_users - GET /api/users - List/search users by query, identity fields, status, and optionally group
• get_user - GET /api/users/<id> - Retrieve a user by ID, email, or username
• create_user - POST /api/users - Create a user with native attributes and custom fields
• get_available_permissions - GET /api/users/permissions - List all known permissions plus custom stored permission names
• update_user - PUT /api/users/<id> - Update a user by ID, email, or username
• delete_user - DELETE /api/users/<id> - Delete a user by ID, email, or username
• get_user_field_layout - GET /api/users/field-layout - Retrieve the single global user field layout

User Groups

• get_user_groups - GET /api/user-groups - List user groups and their permissions
• get_user_group - GET /api/user-groups/<id> - Retrieve a user group by ID or handle
• create_user_group - POST /api/user-groups - Create a user group and set permissions
• update_user_group - PUT /api/user-groups/<id> - Update a user group and its permissions
• delete_user_group - DELETE /api/user-groups/<id> - Delete a user group by ID or handle

System

• health - GET /api/health - Health check endpoint to verify plugin installation and API availability

Commerce: Products

• create_product - POST /api/products - Create product with type, title, SKU, price, and custom fields
• get_product - GET /api/products/<id> - Retrieve product with variants, pricing, and custom fields
• get_products - GET /api/products/search - Search/filter products by type/status/query
• update_product - PUT /api/products/<id> - Update product attributes and custom fields
• delete_product - DELETE /api/products/<id> - Delete product (soft/permanent)
• get_product_types - GET /api/product-types - List available Commerce product types
• get_product_type - GET /api/product-types/<id> - Retrieve product type with field layouts and site settings
• create_product_type - POST /api/product-types - Create product type with title, variant, layout, and site settings
• update_product_type - PUT /api/product-types/<id> - Update product type configuration and site settings
• delete_product_type - DELETE /api/product-types/<id> - Delete product type with impact analysis and force protection

Commerce: Variants

• create_variant - POST /api/variants - Add variant to existing product with SKU, price, and attributes
• get_variant - GET /api/variants/<id> - Retrieve variant with pricing, inventory, and dimensions
• update_variant - PUT /api/variants/<id> - Update variant pricing, SKU, stock, and fields
• delete_variant - DELETE /api/variants/<id> - Delete variant (soft/permanent)

Commerce: Orders

• get_order - GET /api/orders/<id> - Retrieve order with line items, totals, and addresses
• search_orders - GET /api/orders/search - Search/filter orders by email/status/date/payment
• update_order - PUT /api/orders/<id> - Update order status or message
• get_order_statuses - GET /api/order-statuses - List all order statuses with IDs/handles/colors

Commerce: Stores

• get_stores - GET /api/stores - List all stores with checkout/payment/tax configuration
• get_store - GET /api/stores/<id> - Retrieve store with full configuration details
• update_store - PUT /api/stores/<id> - Update store checkout, payment, and pricing settings