> 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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pletor.ai/documentation/api-reference/introduction.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.