Apps

Apps are curated, runnable applications built on top of flows. Each app exposes a configured set of inputs and produces one or more outputs, packaging a flow into a turnkey experience. Use these endpoints to discover available apps and inspect their required inputs and expected outputs, then run them via `POST /app-runs`.

Discover and inspect runnable apps built on flows.

List Apps

get

List available apps with filtering options.

Apps are curated, runnable applications built on top of flows. Each app exposes a set of configured inputs and produces one or more outputs, and can be executed directly via POST /app-runs.

What is listed: the latest version of every active app the caller can see — their own private apps, and workspace and shared apps from their organization, plus every public app. A shared app from another organization is not listed, but can still be fetched by id via GET /apps/{app_id}.

Filtering Options:

• visibility: Filter apps by their visibility status (can be provided multiple times) Options include:

  • private: Only visible to the creator

  • workspace: Visible to everyone in the creator's organization

  • shared: Visible to anyone holding the app's id or link

  • public: Visible to everyone By default, all apps accessible to the caller are returned.

• search: Search apps by name or description (case- and accent-insensitive substring match)

Ordering: by Pletor's curated position, then by most recent run in the caller's organization (never-run apps by creation date), newest first.

Pagination Parameters:

• limit: Maximum number of items to return (default: 20, max: 100)

• cursor: Cursor for pagination (optional)

Response:

• data: List of app summaries with basic information including expected inputs

• has_more: Indicates if there are more results available

• next_cursor: Cursor for the next page of results

Use Case: This is typically the first endpoint called to discover available apps before getting detailed information or executing them.

Error Codes:

• 401: Missing or invalid API key or Bearer token

• 403: The API key is bound to a different organization than X-Organization-Id

• 422: Invalid visibility value, or limit outside 1–100

• 429: Rate limit exceeded — retry after the Retry-After header

Authorizations

X-Api-KeystringRequired

API key for authentication

Query parameters

searchstring · nullableOptional

Case- and accent-insensitive substring match on app name or description

limitinteger · min: 1 · max: 100Optional

Maximum number of items to return

Default: 20

cursorstring · nullableOptional

Cursor for pagination (from next_cursor)

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

has_morebooleanRequired

next_cursorstring · nullableOptional

422

Validation error (validation_error)

application/json

get/apps/

GET /api/public/v1/apps/ HTTP/1.1
Host: api.pletor.ai
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "avatar_url": "text",
      "visibility": "private",
      "estimated_cost": 1,
      "inputs": [
        {
          "id": "text",
          "type": "text",
          "name": "text",
          "required": true,
          "options": [
            "text"
          ],
          "min_selections": 1,
          "max_selections": 1
        }
      ],
      "has_human_review": false
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Get App

get

Get detailed information about a specific app.

This endpoint retrieves comprehensive information about an app, including:

• App metadata (name, description, avatar, visibility)

• Input requirements with types

• Output specifications and formats

• Estimated cost per execution

Access: private apps are readable only by their creator, workspace apps by members of the app's organization, and shared and public apps by any caller. Anything else answers 404, exactly like an app that does not exist.

Input Information: Each app defines specific inputs it accepts, in display order:

• id: Node identifier used when executing the app

• type: Input type (text, image, video, audio, file)

• name: Display name of this input

• required: Whether the input is mandatory

• options, min_selections, max_selections: Constraints for fixed-set inputs. Media options are asset IDs owned by the app's organization, so they are null for callers outside it.

A brand used by the app's flow is fixed when the flow is built: it is not an input and cannot be set per run.

Output Information: Each app specifies what types of content it generates:

• id: Node identifier for the output

• type: Output type (text, images, videos, audio, data)

• description: Description of what this output contains

An output node with no public output type is left out of outputs; its results still appear in the run's results, with type data.

Performance Metrics:

• estimated_cost: Credit cost estimation for running this app (0 when no estimate is available)

Human Review:

• has_human_review: true when a run of this app pauses on a human review step. Resolve each pending review via POST /app-runs/{run_id}/reviews/{review_id} within 1 week, or the run fails.

Use Case: Call this endpoint to understand what inputs an app needs and what outputs it will generate before creating a run.

Error Codes:

• 401: Missing or invalid API key or Bearer token

• 403: The API key is bound to a different organization than X-Organization-Id

• 404: App not found or not accessible

• 422: App has no associated flow definition, or app_id is not a UUID

• 429: Rate limit exceeded — retry after the Retry-After header

Authorizations

X-Api-KeystringRequired

API key for authentication

Path parameters

app_idstring · uuidRequired

Stable ID of the app

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

Complete representation of a runnable app with its inputs, outputs, and cost.

idstring · uuidRequired

Stable app identifier

namestringRequired

App display name

descriptionstringRequired

App description and purpose

avatar_urlstring · nullableOptional

Public CDN URL for the app thumbnail image

visibilitystring · enumRequired

Visibility level: private, workspace, shared, or public

Possible values:

estimated_costintegerRequired

Estimated credit cost per execution, computed when the app's flow version was saved. 0 when no estimate is available

has_human_reviewbooleanOptional

True when this app includes a human review step that will pause a run until a decision is submitted via POST /app-runs/{run_id}/reviews/{review_id}. Poll GET /app-runs/{run_id} for awaiting_human_review while the run is in progress.

Default: false

422

Validation error (validation_error)

application/json

get/apps/{app_id}

GET /api/public/v1/apps/{app_id} HTTP/1.1
Host: api.pletor.ai
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "avatar_url": "https://cdn.example.com/apps/banner.png",
  "description": "Generate marketing banners from a text prompt and logo",
  "estimated_cost": 50,
  "has_human_review": false,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inputs": [
    {
      "id": "uuid-1",
      "name": "Product description",
      "required": true,
      "type": "text"
    },
    {
      "id": "uuid-2",
      "name": "Company logo",
      "required": false,
      "type": "image"
    }
  ],
  "name": "Marketing Banner App",
  "outputs": [
    {
      "description": "Generated banner",
      "id": "uuid-3",
      "type": "images"
    }
  ],
  "visibility": "public"
}