Plainly's API lets other systems start, stop, delete and update tasks, and read your data.
| 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 |
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.
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"
/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.
Add mode=test when starting a task to create a test task named "[Test task]". Test tasks don't send real text messages.
When writing code that calls Plainly: