Introduction
Welcome to the Pletor API documentation.
Integrate Pletor's AI capabilities directly into your apps and workflows — flow discovery, on-brand asset generation, and real-time execution tracking.
Key Features
Flow Discovery — Browse a catalog of flows with detailed descriptions, required inputs, and expected outputs.
Apps — Curated, runnable apps built on top of flows, with every input, setting and output named by slug and described as JSON Schema.
Flexible Execution — Run a flow with
POST /v1/runsor an app withPOST /v2/apps/{app}/runs, providing dynamic inputs including uploaded files.Asset Management — Centralized handling for your files: upload, retrieve, and download assets, and organize them with tags, bookmarks, archiving, and deletion.
Real-Time Tracking — Monitor executions with live updates and retrieve results as soon as they're ready.
Secure API Access — All endpoints require an API key or a Bearer token.
Versioning
Every path starts with its version, under one base URL: https://api.pletor.ai/api/public.
Flows
v1
/v1/flows
Runs (flow executions)
v1
/v1/runs
Assets
v1
/v1/assets
Apps and app runs
v2
/v2/apps
Each resource lives in exactly one current version, so an integration mixes them freely: upload with /v1/assets, then run an app with /v2/apps/{app}/runs. Authentication, rate limits, pagination, errors and external_id work the same in every version.
A version is introduced only where a resource changes shape. Deprecated endpoints keep working and are flagged in this reference:
/v1/appsand/v1/app-runsare superseded by/v2/apps. They keep working unchanged./v1/agentshas been renamed to/v1/flows. The old paths permanently redirect (308) and are removed on 31 December 2026.POST /v1/runsnow takesflow_id; it still acceptsagent_id, and responses carry both until the same date.
The API runs your saved version
Editing a flow in Studio autosaves it as a private draft. The API never reads drafts — it reads the flow's last saved version, the one you create with the save button in the Studio toolbar ("Save in version history").
A flow that has never been saved cannot be used:
GET /v1/flows/{flow_id}answers422andPOST /v1/runsanswers400 invalid_input. It still appears inGET /v1/flows/, with an emptyinputsarray — read that as "not saved yet", not "takes no input".Edits made since the last save do not reach the API. Save again to roll them out to your integration.
GET /v1/flows/{flow_id}describes the saved version, so itsinputsare the onesPOST /v1/runsexpects.
Brand context is part of the flow
The brand (Brain) a flow generates for is set on the flow in Studio, not per request. Brand nodes are never listed in inputs, and no run endpoint accepts a brand or Brain to swap in. Content a flow links from a Brain is read from that Brain as it stands when the run starts. To generate for another brand, run a flow built for that brand.
Authentication
Every request needs one of:
an API key in the
X-Api-Keyheader, ora Bearer JWT in the
Authorization: Bearer <token>header. When both are sent, the Bearer token is used.
Requests act in one organization:
An API key bound to an organization always acts in it.
X-Organization-Idis optional; sending a different organization answers403 forbidden.An unbound API key or a Bearer token acts in the organization named by
X-Organization-Id, or in the user's current (else first) organization when the header is absent. A value that is not a UUID answers400 invalid_input; an organization the user doesn't belong to answers403 forbidden.
A missing or unknown API key, or an invalid or expired token, answers 401 authentication_required with a WWW-Authenticate header.
Rate Limits
Requests authenticated with X-Api-Key are rate limited per API key, in fixed one-minute windows:
Default: 2000 requests/minute
Starting a run —
POST /v1/runs, andPOST /v2/apps/{app}/runsorPOST /v1/app-runs(one shared budget), including their review submissions: 600 requests/minute eachPOST /v1/assets/upload: 600 requests/minute
Each response to an API-key request includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (the Unix time, in seconds, at which the window resets). Over the limit, the API answers 429 rate_limit_exceeded with a Retry-After header and details.retry_after, both in seconds. Bearer-token requests are not counted and carry no rate-limit headers.
Pagination
List endpoints return {"data": [...], "has_more": ..., "next_cursor": ...}. Pass limit (1–100, default 20) and, for the next page, the previous response's next_cursor as cursor, unchanged. has_more is false on the last page.
Errors
Every response carries an X-Request-Id header. Errors use one envelope, with the same ID in details.request_id:
code
HTTP status
Meaning
invalid_input
400
The request is well-formed but can't be applied, e.g. run inputs that don't match the flow. Other 4xx statuses without a code of their own (such as 410 for a deleted asset) also use it, with their own status.
authentication_required
401
Missing or invalid API key or token.
forbidden
403
The organization selected for the request is not allowed. A resource you can't access answers 404, not 403.
not_found
404
The resource doesn't exist or isn't accessible to you.
conflict
409
The request clashes with current state, e.g. a reused external_id or a review that is no longer pending.
validation_error
422
A parameter or body field failed validation (each problem is listed in details.errors as location: message), or the resource can't be used yet, e.g. a flow that was never saved.
rate_limit_exceeded
429
Too many requests; see Rate Limits.
internal_error
500
Unexpected server error. Retry, and quote the request_id if it persists.
run_failed
502
An upstream AI provider failed or its content moderation blocked the request.
service_unavailable
503
A dependency is temporarily unavailable. Retry; a Retry-After header is sent when a wait is known.
timeout
504
The request timed out.
A path or method the API doesn't define answers 404 or 405 with {"detail": "..."} instead of this envelope.
401, 403, 429 and the 5xx codes can come from any endpoint; each endpoint's own error list covers the codes specific to it.
Idempotent requests
Network calls fail halfway, and a blind retry can start a second run (charging you twice) or upload the same file again. To retry safely, attach an external_id to any POST and reuse the same value on the retry.
The first request with a key creates the object and returns it, with
external_idechoed back.Any later request that reuses the key returns
409 conflictinstead of creating a duplicate. Fetch the original withGET /v1/runs?external_id=...(the same filter works on/v2/apps/{app}/runs,/v1/app-runsand/v1/assets).GETandDELETEdon't take a key. Repeating them changes nothing more, but the repeat can answer differently: cancelling a run or app run again answers404, and deleting an asset again answers410.
A key is unique per organization and permanent. Once it has created a run or an upload it stays claimed, even if the run later fails or is canceled, so a genuine re-run needs a new key. Runs and uploads are tracked separately, so the same value can label one run and one upload but not two of either.
Generate your own key. A v4 UUID is a good default; keys can be up to 255 characters, and a longer one is rejected with 422. Keep sensitive data out of it, since it appears in responses. A request that fails validation before the object is created (bad inputs, an oversized key) claims nothing, so you can fix it and retry with the same key.
Quickstart
Find a flow or an app —
GET /v1/flowsorGET /v2/apps.Inspect inputs —
GET /v1/flows/{flow_id}lists a flow's inputs and outputs;GET /v2/apps/{app}returns an app'sinput_schemaandoutput_schemaas JSON Schema.Upload assets (if needed) —
POST /v1/assets/upload.Start a run —
POST /v1/runswith aflow_id, orPOST /v2/apps/{app}/runs, plus inputs.Poll status —
GET /v1/runs/{run_id}orGET /v2/apps/{app}/runs/{run_id}untilstatusleavesin_progressforcompleted,failedorcanceled.Handle human review (if the flow or app has
has_human_review) — whenawaiting_human_reviewistrue, the run is paused: resolve each entry inpending_reviewsviaPOST /v1/runs/{run_id}/reviews/{review_id}orPOST /v2/apps/{app}/runs/{run_id}/reviews/{review_id}to resume execution.Retrieve outputs — a completed flow run lists generated
asset_ids and text inresults; an app run keys them by slug inoutputs.Download assets —
GET /v1/assets/{asset_id}/download.
Last updated

