Getting Started with the Copy.ai Workflows API
This guide will help you get started with Copy.ai's new Workflows API.
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 WFCG-
.
The Workspace API key is only visible to users with the Workspace Admin or Workspace Owner role.
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
Updated 5 months ago