Quick Start Guide

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>

How to Create an API Key

1. Log into copy.ai.
2. Click Configuration in the left sidebar.
3. Click View API Keys.
4. Click Create in the top right of the page.
5. Complete the following fields:
   1. Key Name: Type a unique key name for the API. 
   2. User: Select a user.
   3. Optional. Expiry Date: Select one of the following options:
      1. Never: The key never expires and can be used indefinitely.
      2. 12 Months: The key will expire and no longer be useable after 12 months. Select this option if a key is meant for a limited time use.
6. Click Create.
7. Copy the API Key and save it.

API Endpoints

Find your workflow ID

To use a workflow via the API, you'll need the Workflow ID:

1. Fine and select the workflow in copy.ai.
2. Click the API tab.
3. In the API ENDPOINT field, the workflow ID is at the end of the URL and starts with WFCG-.
   For example:https://api.copy.ai/api/workflow/WCFG-6db59f06-43gh-4ca0-943d-9831cac5ce7b/run

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:

POST https://api.copy.ai/api/webhook

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

Response:

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

Start 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 values for the run.

For example:

POST https://api.copy.ai/api/workflow/<workflow_id>/run

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

Response:

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

Track or poll for progress

To track a workflow run, send a GET request to <https://api.copy.ai/api/workflow/><workflow_id>/run/<run_id>.

For example:

GET https://api.copy.ai/api/workflow/<workflow_id>/run/<run_id>

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

Refer to Get Workflow Run for more information about the workflow run details and available statuses.

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.

For example:

{
  "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": {},
  "credits": 2
}