•••
 
Documentation   /   API   /   API overview
 
 

API overview

 

Plainly's API lets other systems start, stop, delete and update tasks, and read your data.

Endpoints

Endpoint Method Does Authenticated by
https://plainly.com/start POST Starts a task Workflow API key
https://plainly.com/stop POST Stops or restarts a task Workflow API key
https://plainly.com/delete POST Deletes a task Workflow API key and workflow ID
https://plainly.com/hook POST Completes an item in a task Task key and item ID
https://plainly.com/report-json, /report-csv GET Reads a task dataset Dataset key
https://plainly.com/query-json, /query-csv GET Reads a document dataset Dataset key

Keys

  • Workflow API key. Generate it on the workflow's Developer tab. Each key works for one workflow. You can regenerate or delete the key there; either stops the old key working.
  • Dataset key. Generated when you create a shareable link for a dataset in Data Studio. Removing the link stops the key working.
  • Task key. Each task's unique key, available in the workflow as {{checklist_key}} and returned when a task is started.
Important

Treat every key as a password. Keep keys in your server-side code or secrets store, never in web pages, emails or URLs that people can see. Anyone with a workflow API key can start tasks in that workflow, and anyone with a dataset key can read the whole dataset.

Request format

Send POST requests as form data (application/x-www-form-urlencoded or multipart/form-data) over HTTPS. Parameter values should be URL-encoded.

curl -X POST https://plainly.com/start \
  --data-urlencode "key=YOUR_WORKFLOW_API_KEY" \
  --data-urlencode "no_redirect=1" \
  --data-urlencode "name=Jane Doe - Sales Manager" \
  --data-urlencode "passed=first_name_IS_Jane_AND_surname_IS_Doe"

Responses

/start, /stop and /delete return JSON in this form.

On success:

{
  "data": {
    "status": 200,
    "title": "Task started",
    "detail": "1a2b3c4d5e6f7g8h"
  }
}

On error:

{
  "errors": [
    {
      "status": 400,
      "title": "Missing attribute",
      "detail": "You need a key."
    }
  ]
}

The HTTP status code matches status: 200 for success, 400 for a problem with the request and 500 for a problem on Plainly's side. /hook returns plain text instead. See API: Doing task actions.

Testing

Add mode=test when starting a task to create a test task named "[Test task]". Test tasks don't send real text messages.

For AI builders

When writing code that calls Plainly:

  • Always POST to /start, /stop, /delete and /hook, with parameters in the request body, never in the URL.
  • Read the workflow API key and dataset keys from environment variables or a secrets store. Never hard-code them.
  • Send no_redirect=1 to /start to get JSON back. The new task's key is in data.detail.
  • Check both the HTTP status and the presence of errors.
  • Use the same variable names in passed as the workflow's launch form fields.