Overview

Our Workflows API allows you to use any workflow as an API. You can trigger workflow runs, get workflow run details, and register webhooks for workflow events (such as when a workflow run completes)

Authentication

All API routes should be accessed at https://api.copy.ai/api/ and require the x-copy-ai-api-key header field.

See more on the Authentication page.

Finding Your Workflow ID

Many of the API endpoints require a workflow_id.

You can find the workflow ID by going to the API tab on any workflow in the Use as API section.

The workflow_id is shown in the URL of the API Endpoint field. It usually starts with PKGW-.

Webhook Registration

To register a webhook, send a POST request to https://api.copy.ai/api/webhook with a JSON body containing your webhook URL, the event type you want to be notified about, and an optional workflow ID.

For example:

{
  "url": "<https://mywebsite.com/webhook>",
  "eventType": "workflowRun.completed",
  "workflowId": "<my-workflow-id>"
}

You will receive a response with the details of your registered webhook:

{
  "status": "success",
  "data": {
    "id": "<id of webhook>",
    "url": "<https://mywebsite.com/webhook>",
    "eventType": "workflowRun.completed",
    "workflowId": "<my-workflow-id>"
  }
}

Note: If a workflow ID is not included, you will receive events for all workflows in your workspace.

To learn more about webhooks visit the Register Webhook page.

Starting a Workflow Run

To start a workflow run, send a POST request to <https://api.copy.ai/api/workflow/><workflow_id>/run with a JSON body containing the starting value(s) for the run.

For example:

{
  "startVariables": {
	  "Input 1": "<Inputs vary depending on the workflow used.>",
	  "Input 2": "<The best way to see an example is to try it!>"
	},
	"metadata": {
    "api": true  /* example optional metadata to set on the workflow run */
	}
}

You will receive a response with the ID of the started workflow run:

{
  "status": "success",
  "data": {
    "id": "<run_id>"
  }
}

This ID can be used to track the progress of the workflow run and will also be included in the webhook request when the run is completed.

Tracking / Poll for Progress

To track a workflow run, send a GET request to <https://api.copy.ai/api/workflow/><workflow_id>/run/<run_id>. You will get a response in the following format:

{
    "status": "success",
    "data":
    {
        "id": "<run_id>",
        "input":
        { 
          	"Input 1": "Inputs vary depending on the workflow used.",
			      "Input 2": "The best way to see an example is to try it!" 
        },
        "status": "PROCESSING",
        "output":
        {
            "Output 1": "<Outputs vary depending on the workflow used.>",
						"Output 2": "<The best way to see an example is to try it!>"
        },
        "createdAt": "2022-11-18T20:30:07.434Z"
    }
}

To learn more about the workflow run details and statuses available, visit this page: Get Workflow Run

Run Completion

When the run is complete, the status will change to COMPLETE and we will send a POST request to any webhooks registered to receive completion events for the workflow.

Example request:

{
    "type": "workflowRun.completed",
    "workflowRunId": "<run_id>",
    "workflowId": "<workflow_id>",
    "result":
    {
      "Output 1": "<Outputs vary depending on the workflow used.>",
			"Output 2": "<The best way to see an example is to try it!>"
    },
    "metadata":
    {
      /* any metadata set on the workflow run */
    },
    "credits": 2 
}

To learn more about registering a webhook, see this page: Register Webhook