Canva API Integration Guide

Overview

The Canva API integration lets your NINA workflows read the platform's own workflow and execution data. It is a self-integration: a workflow can inspect other workflows in the same organization, list and fetch their executions, and read the results a specific node produced — all from within a running workflow.

This is an internal integration service. It is read-only by design (v1 scope): it exposes no operations that execute, stop, trigger, create, update, or delete workflows or executions. Its purpose is observability and orchestration — for example, letting a monitoring workflow check whether another workflow has completed successfully before acting on its output.

Status

The integration currently supports read access to the platform's workflow and execution data:

• Workflow Discovery: List the workflows visible to the triggering identity, with sorting and filtering
• Workflow Detail: Fetch a single workflow by ID
• Execution History: List the executions of a workflow, with pagination and sorting
• Latest Execution: Fetch the most recent execution of a workflow
• Latest Execution By Status: Fetch the most recent execution of a workflow that carries a given status (e.g. the latest completed run)
• Execution Detail: Fetch a single execution by ID
• Node Results: Fetch the results a specific node produced during a specific execution

Some features are intentionally not supported in this version:

• Write Operations: Creating, updating, or deleting workflows
• Execution Control: Executing, stopping, or triggering workflows
• Real-time Notifications: Webhook or event-based subscriptions
• Cross-organization Access: Reads are always scoped to the triggering organization

Credential Configuration

The Canva API integration uses client credentials authentication against the platform's internal token service.

Authentication Method

Client Credentials Authentication

Authentication using client ID and secret:

Field	Description	Example
Client ID	Client ID for authentication	client_123456789
Secret	Secret for authentication	secret_abcdef123456789

Note: This is an internal, platform-managed integration. The credential is normally provisioned once by platform administrators rather than created ad hoc per user — a single internal credential typically serves the platform. Contact your platform administrator if the integration is not already available in your environment.

Creating a Canva API Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "Canva API Internal")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Canva API"
   • Client ID: Enter your client ID
   • Secret: Enter your client secret
4. Click Test Connection to verify credentials
5. Click Save to store the credential

Supported Resources and Operations

The Canva API integration exposes a single resource, Workflows, with the following operations:

Workflows

Operation	Description
List Workflows	List the workflows visible to the triggering identity
Get Workflow	Fetch a single workflow by ID
List Workflow Executions	List the executions of a workflow
Get Latest Workflow Execution	Fetch the most recent execution of a workflow
Get Latest Workflow Execution By Status	Fetch the most recent execution of a workflow that has a given status
Get Workflow Execution	Fetch a single workflow execution by ID
Get Node Results	Fetch the results a node produced during a workflow execution

Operation Parameters

List Workflows (list-workflows)

Returns all workflows the triggering identity can see (not paginated).

Parameter	Required	Description
sort_by	No	Field to sort by: created_at, updated_at, name, favorite, category, vertical, last_executed
sort_order	No	asc or desc (default desc)
favorites_only	No	If true, only return favorited workflows
category_ids	No	Filter by category IDs (comma-separated, OR logic)
vertical_ids	No	Filter by vertical IDs (comma-separated, OR logic)

Get Workflow (get-workflow)

Parameter	Required	Description
workflow_id	Yes	UUID of the workflow to fetch

List Workflow Executions (list-workflow-executions)

Parameter	Required	Description
workflow_id	Yes	UUID of the parent workflow
page	No	Page number to retrieve (1-indexed)
page_size	No	Number of items per page
sort_by	No	Field to sort by: created_at, start_time, end_time, status
sort_order	No	asc or desc (default desc)
include_s3_urls	No	If true, include presigned S3 URLs (valid for 1 hour) for downloading output files

Get Latest Workflow Execution (get-latest-workflow-execution)

Parameter	Required	Description
workflow_id	Yes	UUID of the parent workflow

Get Latest Workflow Execution By Status (get-latest-workflow-execution-by-status)

Scans the most-recent executions newest-first and returns the first one matching the requested status.

Parameter	Required	Description
workflow_id	Yes	UUID of the parent workflow
status	Yes	Execution status to match: pending, running, held, held_branch, partially_complete, complete, failed, partial-fail
scan_limit	No	How many of the most-recent executions to inspect (default 50, max 200)
include_s3_urls	No	If true, include presigned S3 URLs (valid for 1 hour)

Get Workflow Execution (get-workflow-execution)

Parameter	Required	Description
workflow_execution_id	Yes	UUID of the workflow execution to fetch
include_s3_urls	No	If true, include presigned S3 URLs (valid for 1 hour)

Get Node Results (get-node-results)

Parameter	Required	Description
node_id	Yes	UUID of the node
workflow_execution_id	Yes	UUID of the workflow execution
include_s3_urls	No	If true, include presigned S3 URLs (valid for 1 hour)

Parameter Merging

The Canva API integration follows NINA's standard parameter merging behavior:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Canva API Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a Canva API Integration Node executes, it combines parameters from all sources, with node parameters taking precedence, and uses the result to execute the operation. This means an upstream node can supply a workflow_id or workflow_execution_id and a downstream Canva API node can consume it without hard-coding.

Examples

Listing Workflows

Retrieve workflows sorted by most recently executed:

{
  "resource": "workflows",
  "operation": "list-workflows",
  "parameters": {
    "sort_by": "last_executed",
    "sort_order": "desc",
    "favorites_only": false
  }
}

Getting a Single Workflow

{
  "resource": "workflows",
  "operation": "get-workflow",
  "parameters": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Listing a Workflow's Executions

Retrieve the second page of executions, sorted by status, including download URLs:

{
  "resource": "workflows",
  "operation": "list-workflow-executions",
  "parameters": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "page": 2,
    "page_size": 25,
    "sort_by": "start_time",
    "sort_order": "desc",
    "include_s3_urls": true
  }
}

Getting the Latest Execution

{
  "resource": "workflows",
  "operation": "get-latest-workflow-execution",
  "parameters": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Getting the Latest Completed Execution

Use this when a workflow inspects its own history and must skip the currently-running execution (itself). Scanning newest-first, it returns the first execution whose status is complete:

{
  "resource": "workflows",
  "operation": "get-latest-workflow-execution-by-status",
  "parameters": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "complete",
    "scan_limit": 50
  }
}

If no execution with the requested status is found within scan_limit, the operation returns an explicit error naming the status, the workflow, and the number of executions scanned.

Getting a Single Execution by ID

{
  "resource": "workflows",
  "operation": "get-workflow-execution",
  "parameters": {
    "workflow_execution_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "include_s3_urls": true
  }
}

Getting a Node's Results

{
  "resource": "workflows",
  "operation": "get-node-results",
  "parameters": {
    "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "workflow_execution_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "include_s3_urls": true
  }
}

Response Structure

List Responses

List operations return a data array with a total count:

{
  "data": [
    {
      "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "complete",
      "start_time": "2026-07-30T09:00:00Z",
      "end_time": "2026-07-30T09:04:12Z"
    }
  ],
  "total": 1
}

Single-Object Responses

Single-fetch operations (including get-latest-workflow-execution-by-status) return the object under data:

{
  "data": {
    "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "complete",
    "start_time": "2026-07-30T09:00:00Z",
    "end_time": "2026-07-30T09:04:12Z",
    "node_executions": [
      {
        "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
        "status": "complete",
        "output_file_url": "workflows/.../result.json",
        "output_s3_url": "https://...signed-url..."
      }
    ]
  }
}

When include_s3_urls is true, each node execution's output_s3_url carries a presigned link valid for one hour; otherwise only the stored output_file_url path is returned.

Execution Status Values

Status	Meaning
pending	Queued, not yet started
running	Currently executing
held / held_branch	Paused awaiting input or a held branch
partially_complete	Finished with some branches incomplete
complete	Finished successfully
failed	Finished with an error
partial-fail	Finished with some branches failed

Integration in Workflow Context

The Canva API integration is most useful for orchestration and monitoring patterns that reason about other workflows:

1. Wait-for-completion gating:

   • Schedule Node → Canva API Node (get-latest-workflow-execution-by-status, status: complete) → Condition Node → downstream action on the completed run's output

2. Self-referential "last good run":

   • Canva API Node (get-latest-workflow-execution-by-status, status: complete) → Script Node (diff against current inputs) → branch accordingly (skips the running self-execution)

3. Cross-workflow result consumption:

   • Canva API Node (get-workflow → get-latest-workflow-execution) → Canva API Node (get-node-results) → Script Node (process another workflow's output)

4. Execution health dashboard:

   • Canva API Node (list-workflows, sort_by: last_executed) → loop → Canva API Node (list-workflow-executions, sort_by: status) → Dashboard Node

5. Failure alerting:

   • Schedule Node → Canva API Node (get-latest-workflow-execution-by-status, status: failed) → Slack Integration Node (alert on the latest failure)

Best Practices

1. Prefer get-latest-workflow-execution-by-status for self-inspection: A workflow reading its own latest execution will otherwise get itself back in running state. Filter by complete (or the status you need) to skip it.

2. Tune scan_limit to the history depth: The by-status scan inspects the most-recent executions only. If a workflow runs very frequently and the target status is rare, raise scan_limit (up to 200) so older matches are reachable. If no match is found in the window, the operation errors explicitly rather than returning stale data.

3. Request include_s3_urls only when you need file contents: The presigned URLs are valid for one hour; omit the flag when you only need statuses or metadata.

4. Pass IDs via upstream nodes: Rely on parameter merging to feed workflow_id / workflow_execution_id from earlier nodes instead of hard-coding UUIDs.

5. Remember reads are org-scoped: The integration only returns workflows and executions belonging to the triggering organization.

Troubleshooting

Common Issues and Solutions

Issue	Possible Solution
Authentication failed	Verify the client ID and secret are valid; confirm the internal credential is provisioned in your environment
unsupported protocol scheme ""	The credential is missing its service domain; contact your platform administrator to re-provision it
Workflow / execution not found	Confirm the UUID is correct and belongs to the triggering organization
no execution with status "..." found	The requested status wasn't present within scan_limit recent executions; raise scan_limit or verify a matching run exists
Node results empty	Confirm the node_id produced output for that specific execution (results are per node, per execution)
Unexpected running result	You are fetching your own latest execution; use get-latest-workflow-execution-by-status with status: complete

Error Response Format

Failures are surfaced as standard integration errors, for example:

{
  "error": true,
  "message": "no execution with status \"complete\" found within the 50 most recent executions of workflow 550e8400-...",
  "details": {
    "operation": "get-latest-workflow-execution-by-status"
  }
}

Support

If you encounter issues with the Canva API integration, please contact our support team with:

• The operation you were attempting
• The workflow and/or execution IDs involved (without sensitive data)
• Any error messages received
• The workflow context where the issue occurred

Updated: 2026-07-30