> For the complete documentation index, see [llms.txt](https://docs.pletor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pletor.ai/documentation/api-reference/introduction.md).

# 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_id`s and text outputs.
8. **Download assets** — `GET /assets/{asset_id}/download`.