Introduction

Welcome to the Pletor API documentation.

Integrate Pletor's AI capabilities directly into your apps and workflows — agent discovery, on-brand asset generation, and real-time execution tracking.

Key Features

• Agent Discovery — Browse a catalog of AI agents with detailed descriptions, required inputs, and expected outputs.

• App Discovery — Browse curated, runnable apps built on top of flows. Apps are an alternative to agents: run them via POST /app-runs with an app_id.

• Flexible Execution — Create agent runs via POST /runs and app runs via POST /app-runs, providing dynamic inputs including uploaded files.

• Asset Management — Centralized handling for your files: upload, retrieve, and share assets easily.

• Real-Time Tracking — Monitor executions with live updates and retrieve results as soon as they're ready.

• Secure API Access — All endpoints are protected with API key authentication.

Authentication

All requests require either an API key in the X-Api-Key header, or a Bearer JWT in the Authorization header.

Rate Limits

Rate limits are per API key:

• Default: 2000 requests/minute

• POST /runs and POST /app-runs: 600 requests/minute

• POST /assets/upload: 600 requests/minute

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

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_id echoed back.

• Any later request that reuses the key returns 409 conflict instead of creating a duplicate. Fetch the original with GET /runs?external_id=... (the same filter works on /app-runs and /assets).

• GET and DELETE don't take a key; repeating those is already safe.

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

1. List agents or apps — GET /agents or GET /apps to find one that fits your use case.

2. Inspect inputs — GET /agents/{id} or GET /apps/{id} to see required inputs and expected outputs.

3. Upload assets (if needed) — POST /assets/upload.

4. Create a run — POST /runs with an agent_id for agents, or POST /app-runs with an app_id for apps, plus inputs.

5. Poll status — GET /runs/{run_id} (agent runs) or GET /app-runs/{run_id} (app runs) until completed.

6. Handle human review (agent runs, if applicable) — when awaiting_human_review is true, resolve each entry in pending_reviews via POST /runs/{run_id}/reviews/{review_id} to resume execution.

7. Retrieve outputs — inspect the completed run's results array to find generated asset_ids and text outputs.

8. Download assets — GET /assets/{asset_id}/download.