README

Comprehensive Canva Connect API toolkit for Coqui. Provides structured access to the Canva REST API v1 for design management, asset uploads, exports, folders, comments, brand templates, and autofill.

Installation

composer require coquibot/coqui-toolkit-canva

The toolkit is auto-discovered by Coqui on startup. No additional configuration required.

Authentication Setup

1. Create a Canva Integration

1. Go to the Canva Developer Portal
2. Create a new integration (or use an existing one)
3. Set the redirect URL to http://127.0.0.1 (the toolkit uses a random high port for the callback)
4. Note your Client ID and Client Secret

2. Configure Credentials

In Coqui, set your credentials:

credentials(action: "set", key: "CANVA_CLIENT_ID", value: "your-client-id")
credentials(action: "set", key: "CANVA_CLIENT_SECRET", value: "your-client-secret")

3. Authenticate

canva_auth(action: "login")

This opens your browser for OAuth authorization. After granting access, the toolkit stores tokens securely and auto-refreshes them.

Required Scopes

The toolkit requests these scopes during OAuth:

Tools Reference

canva_auth

Manage OAuth authentication.

canva_design

Create and manage Canva designs.

canva_export

Export designs to various formats. Jobs are polled automatically.

canva_asset

Upload and manage media assets.

canva_folder

Organize designs and assets into folders.

canva_comment

Manage design comments and threads.

canva_user

Get authenticated user information.

canva_brand_template (Enterprise)

Manage brand templates. Requires Canva Enterprise subscription.

canva_autofill (Enterprise)

Create designs from brand templates with data. Requires Canva Enterprise.

Workflow Examples

Create and Export a Presentation

canva_auth(action: "status")
canva_design(action: "create", design_type: "presentation", title: "Q4 Review")
canva_export(action: "create", design_id: "DAFxyz123", format: "pdf")

Upload Assets and Organize

canva_asset(action: "upload", file_path: "/path/to/logo.png", name: "Company Logo")
canva_folder(action: "create", name: "Brand Assets")
canva_folder(action: "move_item", folder_id: "FAFabc", item_id: "AAFxyz")

Autofill a Brand Template (Enterprise)

canva_brand_template(action: "list", query: "social")
canva_brand_template(action: "dataset", template_id: "BTFxyz")
canva_autofill(action: "create", template_id: "BTFxyz", data: '{"headline": "Summer Sale", "discount": "30% off"}')
canva_export(action: "create", design_id: "...", format: "png")

Add Design Feedback

canva_comment(action: "create_thread", design_id: "DAFxyz", message: "The logo needs more padding on the left")
canva_comment(action: "list_threads", design_id: "DAFxyz")

MCP Integration (Canva AI Connector)

In addition to this REST API toolkit, Canva offers an MCP server (Canva AI Connector) for design operations. You can use both simultaneously — the REST toolkit for structured programmatic access and the MCP connector for interactive design operations.

Setting Up the Canva AI Connector

Add to your .workspace/mcp.json:

{
    "servers": {
        "canva": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@anthropic-ai/canva-mcp-server"],
            "env": {
                "CANVA_CLIENT_ID": "${CANVA_CLIENT_ID}",
                "CANVA_CLIENT_SECRET": "${CANVA_CLIENT_SECRET}"
            }
        }
    }
}

The MCP connector shares the same CANVA_CLIENT_ID and CANVA_CLIENT_SECRET credentials.

Designer Role

The toolkit includes a designer agent role optimized for creative work. Spawn it as a child agent:

spawn_agent(role: "designer", task: "Create a presentation deck for our Q4 review")

The designer role brings expertise in visual design principles, brand consistency, and Canva workflow patterns.

Rate Limits

Canva enforces per-user rate limits:

The toolkit automatically retries once on rate limit (429) responses using the Retry-After header.

Enterprise Features

Brand templates and autofill require a Canva Enterprise subscription. Non-Enterprise users will see a clear error message when attempting to use these features. All other tools work with any Canva plan.

Development

# Install dependencies
composer install

# Run tests
vendor/bin/pest

# Static analysis
vendor/bin/phpstan analyse

License

MIT