Base URL
Every request goes to:
https://api.ploton.ai/v1HTTPS only. Plain HTTP requests get rejected.
Authentication
Pass your API key as a Bearer token in the Authorization header:
curl https://api.ploton.ai/v1/tasks \
-H "Authorization: Bearer pk_live_your_api_key"pk_test_ and pk_live_ keys both work on all endpoints. See Authentication for key types and rotation.
Request format
- Request bodies are JSON with
Content-Type: application/json - Parameters are case-sensitive
- Dates use ISO 8601 format (
2025-06-15T14:22:03Z) - IDs are prefixed strings (
task_8xK2mP,user_123)
Response format
Successful responses
Single resources come back as top-level objects:
{
"id": "task_8xK2mP",
"status": "running",
"tool": "crm",
"created_at": "2025-06-15T14:22:00Z"
}Collections come in a data array with a has_more flag for pagination:
{
"data": [
{ "id": "task_8xK2mP", "status": "complete" },
{ "id": "task_3nL7pR", "status": "running" }
],
"has_more": true
}Error responses
Errors return an error object with a code and message:
{
"error": {
"code": "invalid_api_key",
"message": "The API key provided is not valid. Check that you're using the correct key and that it hasn't been revoked."
}
}HTTP status codes
| Status | Meaning |
|---|---|
200 | Success |
201 | Resource created |
400 | Bad request — check your parameters |
401 | Unauthorized — invalid or missing API key |
403 | Forbidden — valid key, but not enough permissions |
404 | Resource not found |
409 | Conflict — e.g., cancelling a task that already finished |
422 | Unprocessable entity — valid JSON, but the content fails validation |
429 | Rate limit exceeded — back off and retry |
500 | Server error — retry with backoff, contact support if it keeps happening |
Error codes
| Code | HTTP Status | Description | What to do |
|---|---|---|---|
invalid_api_key | 401 | API key is malformed or revoked | Check key format, generate a new key from the dashboard |
missing_api_key | 401 | No Authorization header provided | Add the Bearer token header |
invalid_request | 400 | Request body is not valid JSON or missing required fields | Check the request format and required parameters |
task_not_found | 404 | No task exists with the given ID | Verify the task ID |
task_already_complete | 409 | Cannot cancel or modify a completed/failed task | No action needed — check the task’s final status |
rate_limit_exceeded | 429 | Too many requests | Back off and retry. Check Retry-After header for timing. |
prompt_too_long | 422 | Task prompt exceeds the maximum length (10,000 characters) | Shorten the prompt or split into multiple tasks |
internal_error | 500 | Something went wrong on Ploton’s side | Retry with exponential backoff. If persistent, contact support. |
Rate limits
| Plan | Requests per minute | Concurrent tasks |
|---|---|---|
| Prototyping (free) | 100 | 10 |
| Production | 1,000 | 100 |
| Enterprise | Custom | Custom |
All plans get full API access. See ploton.ai/pricing for current details.
- Prototyping — Free. Unlimited tasks, limited users.
- Production — $0.75/task, pay-as-you-go.
- Trained Tasks — $150/month add-on.
- Enterprise — Contact sales for 500K+ tasks/month.
When you hit the rate limit, the API returns 429 with a Retry-After header telling you how many seconds to wait.
# Response headers on a 429
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718459532Pagination
List endpoints support limit and offset:
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
limit | integer | 20 | 100 | Number of items per page |
offset | integer | 0 | — | Number of items to skip |
Check has_more in the response to see if there are more pages.
# First page
curl "https://api.ploton.ai/v1/tasks?limit=20&offset=0" \
-H "Authorization: Bearer $PLOTON_API_KEY"
# Second page
curl "https://api.ploton.ai/v1/tasks?limit=20&offset=20" \
-H "Authorization: Bearer $PLOTON_API_KEY"Idempotency
POST /v1/tasks is not idempotent by default — calling it twice creates two tasks. To get retry safety (useful over flaky networks), include an Idempotency-Key header:
curl -X POST https://api.ploton.ai/v1/tasks \
-H "Authorization: Bearer $PLOTON_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: req_unique_abc123" \
-d '{"prompt": "Fetch user contacts from the connected CRM"}'Keys are valid for 24 hours. A request with a previously-used key returns the original response without creating a new task.