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