Getting Started with the Copy.ai API

This page will help you get started with Copy.ai. You'll be up and running in a jiffy!

Overview

Our API allows you to register webhooks and trigger workflow runs. When a workflow run is completed, a request will be sent to your registered webhook with the results.

Note: API access is currently open to beta customers. Please contact us to get your API Key and build workflows.

Authentication

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

x-copy-ai-api-key <api key goes here>

For all API requests you must also pass the Content-Type header as follows:

Content-Type: application/json

Note: API access is currently open to beta customers. Please contact us to get your API Key

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 and the event type you want to be notified about. For example:

{
  "url": "<https://mywebsite.com/webhook>",
  "eventType": "workflowRun.completed"
}

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"
  }
}

Starting a Workflow Run

To start a workflow run, send a POST request to <https://api.copy.ai/api/workflow/><workflow_uuid>/run with a JSON body containing the starting value for the run. For example:

{
  "startVariables": {
        "<variable>":"https://copy.ai",
    },
    "metadata": {
        <any meta data here>
    }
}

Note: API access is currently open to beta customers. Please contact us to get your API Key and build workflows.

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

{
  "status": "success",
  "data": {
    "id": "<id of workflow run>"
  }
}

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_uuid>/run/<workflow_run_id>. You will get a response in the following format:

{
    "status": "success",
    "data":
    {
        "id": "<workflow run id>",
        "input":
        { 
            ... 
        },
        "status": "PROCESSING",
        "output":
        {
            ...
        },
        "createdAt": "2022-11-18T20:30:07.434Z"
    }
}

When the run is complete, the status will change to COMPLETE.

Run Completion

When the run is completed, we will send a POST request to your webhook. Example request:

{
    "type": "workflowRun.completed",
    "workflowId": "<id of workflow>",
    "workflowRunId": "<id of run>",
    "result": { "output": "<result of workflow>" },
        "metadata":
        {
            <any meta data here>
        },
}