openapi: 3.1.0
info:
  title: Pletor - Public API
  description: |
    ## 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`.
  version: 1.0.0
paths:
  /agents/:
    get:
      tags:
      - agents
      summary: List Agents
      description: |-
        List available AI agents with filtering options.

        This endpoint returns a paginated list of AI agents that can generate various types of
        content including images, videos, text, and other creative assets.

        **Filtering Options:**
        - `tags`: Filter agents by tags (can be provided multiple times)
        - `visibility`: Filter agents by their visibility status (can be provided multiple times)
           Options include:
            - PRIVATE: Internal organization's agents
            - SHARED: Agents shared by the user
            - PUBLIC: Pletor public agents
           By default, only PRIVATE and SHARED agents are returned.
        - `search`: Search agents by name (case-insensitive)

        **Pagination Parameters:**
        - `limit`: Maximum number of items to return (default: 20, max: 100)
        - `cursor`: Cursor for pagination (optional)

        **Response:**
        - `data`: List of agent 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 agents
        before getting detailed information or executing them.
      operationId: list_agents_agents__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tags
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          title: Tags
      - name: visibility
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/FlowVisibility'
          - type: 'null'
          title: Visibility
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search agents by name
          title: Search
        description: Search agents by name
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of items to return
          default: 20
          title: Limit
        description: Maximum number of items to return
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Cursor for pagination (from next_cursor)
          title: Cursor
        description: Cursor for pagination (from next_cursor)
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPaginatedResponse_AgentSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}:
    get:
      tags:
      - agents
      summary: Get Agent
      description: |-
        Get detailed information about a specific AI agent.

        This endpoint retrieves comprehensive information about an AI agent, including:
        - Agent metadata (name, description, category, tags)
        - Input requirements with types
        - Output specifications and formats
        - Performance metrics and cost estimates

        **Input Information:**
        Each agent defines specific inputs it requires:
        - `id`: Node identifier used when executing the agent
        - `type`: Input type (text_input, image_input, video_input, file_input)
        - `description`: Description of what this input does

        **Output Information:**
        Each agent specifies what types of content it generates:
        - `id`: Node identifier for the output
        - `type`: Output type (text, images, videos, files, data)
        - `description`: Description of what this output contains

        **Performance Metrics:**
        - `estimated_cost`: Credit cost estimation for running this agent

        **Use Case:** Call this endpoint to understand what inputs an agent needs and what
        outputs it will generate before creating a generation request.

        **Error Codes:**
        - `404`: Agent not found or not accessible
        - `422`: Agent has no active version
      operationId: get_agent_agents__agent_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /apps/:
    get:
      tags:
      - apps
      summary: List Apps
      description: |-
        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`.

        **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 via a shared link
            - public: Visible to everyone
           By default, all apps accessible to the caller are returned.
        - `search`: Search apps by name or description (case-insensitive)

        **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.
      operationId: list_apps_apps__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: visibility
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/FlowApplicationVisibility'
          - type: 'null'
          title: Visibility
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search apps by name or description
          title: Search
        description: Search apps by name or description
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of items to return
          default: 20
          title: Limit
        description: Maximum number of items to return
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Cursor for pagination (from next_cursor)
          title: Cursor
        description: Cursor for pagination (from next_cursor)
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPaginatedResponse_AppSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /apps/{app_id}:
    get:
      tags:
      - apps
      summary: Get App
      description: |-
        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

        **Input Information:**
        Each app defines specific inputs it requires:
        - `id`: Node identifier used when executing the app
        - `type`: Input type (text, image, video, audio, brand, file)
        - `name`: Display name of this input
        - `required`: Whether the input is mandatory
        - `options`, `min_selections`, `max_selections`: Constraints for fixed-set inputs

        **Output Information:**
        Each app specifies what types of content it generates:
        - `id`: Node identifier for the output
        - `type`: Output type (text, images, videos, files, audio, data)
        - `description`: Description of what this output contains

        **Performance Metrics:**
        - `estimated_cost`: Credit cost estimation for running this app

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

        **Error Codes:**
        - `404`: App not found or not accessible
        - `422`: App has no associated flow definition
      operationId: get_app_apps__app_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: app_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: App Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /assets/:
    get:
      tags:
      - assets
      summary: List Assets
      description: |-
        List assets with pagination and optional filtering.

        This endpoint returns a paginated list of assets belonging to your organization.
        You can optionally filter by a specific list of asset IDs, by the agent that
        produced them, and/or by the specific run that produced them.

        **Primary Use Cases:**
        - Browse all your assets with pagination
        - Retrieve specific assets using their IDs
        - Fetch every asset produced by a given agent across all its runs
        - Fetch every asset produced by a specific run
        - Verify the provenance of a known asset list (combine `asset_ids` with
          `agent_id` or `run_id`)

        **Pagination Parameters:**
        - `limit`: Maximum number of items to return (default: 20, max: 100)
        - `cursor`: Cursor for pagination (optional)

        **Filtering Parameters:**
        - `asset_ids`: Optional list of UUIDs to filter specific assets.
        - `agent_id`: Optional agent UUID. Returns all assets produced by that agent
          across every run.
        - `run_id`: Optional run UUID. Returns all assets produced by that single run.
        - All three filters compose as an AND. For example,
          `?asset_ids=<id>&agent_id=<agent>` returns the asset only if it was
          produced by that agent; otherwise the response is empty.
        - `agent_id` and `run_id` only match assets that were produced by an agent
          run, so uploaded assets are excluded when either filter is set.

        **Response:**
        Returns a `CursorPaginatedResponse` object containing:
        - `data`: List of `AssetSummary` objects. Each asset includes `agent_id` and
          `run_id` so you can correlate it back to the agent / run that produced it.
        - `has_more`: Indicates if there are more results available
        - `next_cursor`: Cursor for the next page

        **Access Control:**
        - Only assets belonging to your organization are returned
        - Assets not found or not accessible are silently excluded
      operationId: list_assets_assets__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: asset_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid
          - type: 'null'
          description: Restrict the result to this list of asset IDs. Combines with `agent_id` / `run_id` as an AND — an asset is only returned if it is in this list and matches every other filter.
          title: Asset Ids
        description: Restrict the result to this list of asset IDs. Combines with `agent_id` / `run_id` as an AND — an asset is only returned if it is in this list and matches every other filter.
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Return only assets produced by this agent (across all its runs). Uploaded assets are never returned by this filter.
          title: Agent Id
        description: Return only assets produced by this agent (across all its runs). Uploaded assets are never returned by this filter.
      - name: run_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Return only assets produced by this specific run. Uploaded assets are never returned by this filter.
          title: Run Id
        description: Return only assets produced by this specific run. Uploaded assets are never returned by this filter.
      - name: external_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Return the asset you uploaded with this reference id. Use after a 409 on upload to fetch the existing asset.
          title: External Id
        description: Return the asset you uploaded with this reference id. Use after a 409 on upload to fetch the existing asset.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of items to return
          default: 20
          title: Limit
        description: Maximum number of items to return
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Cursor for pagination (from next_cursor)
          title: Cursor
        description: Cursor for pagination (from next_cursor)
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPaginatedResponse_AssetSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /assets/{asset_id}:
    get:
      tags:
      - assets
      summary: Get Asset
      description: |-
        Retrieve complete metadata for a specific asset.

        This endpoint returns detailed information about an asset, including its metadata,
        access URLs, and processing information. Use this when you need complete asset
        details rather than just summary information.

        **Parameters:**
        - `asset_id`: UUID of the asset to retrieve

        **Response:**
        Returns a complete `Asset` object with all `AssetSummary` fields plus:
        - `asset_metadata`: Dictionary with processing metadata and technical details
        - `is_flow_output_sample`: Whether this asset is a sample from agent execution
        - `blur_hash`: Hash for progressive image loading (images only)

        **Access Control:**
        - Asset must be owned by the authenticated user's organization, or
        - Asset must have "public" or "shared" visibility

        **Errors:**
        - 404: Asset not found or access denied
      operationId: get_asset_assets__asset_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: asset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Asset Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - assets
      summary: Delete Asset
      description: |-
        Soft-delete an asset.

        Marks the asset as deleted so it stops appearing in listings and can no
        longer be downloaded. The underlying file is retained and the operation is
        reversible by an administrator.

        **Parameters:**
        - `asset_id`: UUID of the asset to delete

        **Access Control:**
        - Asset must be owned by the authenticated user's organization. Assets from
          other organizations are reported as `404` rather than deleted.

        **Response:**
        - `204 No Content` on success

        **Errors:**
        - 404: Asset not found or access denied
        - 410: Asset has already been deleted
      operationId: delete_asset_assets__asset_id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: asset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Asset Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /assets/upload/:
    post:
      tags:
      - assets
      summary: Upload Asset
      description: |-
        Upload an asset file.

        This endpoint handles the complete asset upload process in a single request.
        Simply send your file and get back a complete, ready-to-use asset.

        **Request (multipart/form-data):**
        - `file`: The file to upload (required)
        - `visibility`: Asset visibility level (default: "private")
          - `"private"`: Only accessible by your organization
          - `"public"`: Accessible by everyone
          - `"shared"`: Accessible via shared links
        - `filename`: Optional custom display filename
        - `external_id`: Optional client-supplied reference id (≤255 chars), unique
          per organization. Makes the upload safe to retry — reusing a key returns
          `409` instead of a duplicate asset; fetch the existing one via
          `GET /assets?external_id=`.

        **Supported File Types:**
        Images, videos, audio files, and documents (PNG, JPEG, MP4, PDF, etc.)

        **Response:**
        Returns a complete `Asset` object ready to use immediately (with `external_id`
        echoed).

        **Processing:**
        The asset is automatically processed in the background after upload,
        including thumbnail generation and metadata extraction.

        **Errors:**
        - 400: Invalid or unsupported file type, or file cannot be read
        - 409: `external_id` already used by another asset (don't retry; GET it instead)
        - 413: File too large
        - 500: Server error during upload or processing
        - 503: Storage service temporarily unavailable
      operationId: upload_asset_assets_upload__post
      security:
      - APIKeyHeader: []
      parameters:
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_asset_assets_upload__post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /assets/{asset_id}/download:
    get:
      tags:
      - assets
      summary: Download Asset
      description: |-
        Download the actual file content of an asset.

        This endpoint streams the binary file content of an asset. It's used to retrieve
        generated assets from agent executions, download uploaded files, or access
        assets for further processing.

        **Primary Use Cases:**
        - Download generated images/videos from completed agent executions
        - Retrieve uploaded assets for local processing or display

        **Parameters:**
        - `asset_id`: Asset UUID identifier
        - `svg`: Optional boolean to convert images to SVG format (experimental feature)

        **Access Control:**
        - Same access rules as `GET /{asset_id}` endpoint
        - Asset must be accessible to the authenticated user

        **Errors:**
        - 404: Asset not found or access denied
        - 410: Asset file no longer available (expired or deleted)
      operationId: download_asset_assets__asset_id__download_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: asset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Asset Id
      - name: svg
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Convert image to SVG format if applicable
          title: Svg
        description: Convert image to SVG format if applicable
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /runs/:
    post:
      tags:
      - runs
      summary: Create Run
      description: |-
        Create and start a new agent execution run.

        This endpoint launches the execution of an AI agent with the provided inputs.
        The execution runs asynchronously, allowing you to monitor progress and retrieve
        results when complete.

        **Idempotency with `external_id`:** Optionally pass an `external_id` (e.g. your
        own order or job id). It is **unique per organization**: the first request with
        a given key starts the run; any later write reusing that key — including a
        dropped-response retry — is rejected with **`409 conflict`** instead of starting
        (and charging) a duplicate. To fetch the run a key already created, use
        `GET /runs?external_id=...`. The id is echoed on every run response.

        - Scope: per organization, across **all** runs (agent and app share the key
          space) and **all** statuses — a key, once used, stays used.
        - On `409`, do **not** keep retrying the create; `GET /runs?external_id=` to
          retrieve the existing run. To start a genuinely new run, use a new `external_id`.

        **How to Build Inputs:**

        1. **First, get agent details**: Call `GET /agents/{agent_id}` to retrieve the agent configuration
        2. **Examine the `inputs` array**: Each object defines what input the agent expects:
           - `id`: Use this as the `id` in your input object
           - `type`: Determines the input format (see below)
           - `description`: Explains what this input does

        3. **Format inputs based on type**:

        **Text Inputs** (`text_input` type):
        ```json
        {
            "id": "text_input_node_id",
            "value": "Your text content here"
        }
        ```

        **Asset Inputs** (`image_input`, `video_input`, `file_input` types):
        ```json
        {
            "id": "image_input_node_id",
            "value": {
                "asset_ids": ["uuid1", "uuid2"]
            }
        }
        ```
        Note: Upload assets first via `POST /assets/upload` to get the UUIDs

        **Complete Example Workflow:**

        1. Get agent configuration:
        ```bash
        GET /agents/550e8400-e29b-41d4-a716-446655440000
        # Response shows inputs: [
        #   {"id": "uuid-1", "type": "text_input", "description": "Product description"},
        #   {"id": "uuid-2", "type": "image_input", "description": "Company logo"}
        # ]
        ```

        2. Upload assets if needed:
        ```bash
        POST /assets/upload
        # Response: {"id": "asset-uuid-123", ...}
        ```

        3. Create run with matching inputs:
        ```json
        {
            "agent_id": "550e8400-e29b-41d4-a716-446655440000",
            "inputs": [
                {
                    "id": "uuid-1",
                    "value": "Create a marketing banner for a tech startup"
                },
                {
                    "id": "uuid-2",
                    "value": {
                        "asset_ids": ["asset-uuid-123"]
                    }
                }
            ]
        }
        ```

        **Response:**
        - Run object with execution details and initial status
        - Use `id` field to monitor progress via `GET /runs/{run_id}`

        **Running an app instead?** Apps have their own surface — use `POST /app-runs`
        with an `app_id`. See the Apps and App Runs sections.

        **Error Codes:**
        - `400`: Invalid input format or missing required inputs
        - `404`: Agent not found or not accessible
      operationId: create_run_runs__post
      security:
      - APIKeyHeader: []
      parameters:
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - runs
      summary: List Runs
      description: |-
        List agent execution runs with filtering options.

        This endpoint returns a paginated list of agent execution runs with their
        current status and basic metadata. App runs are listed separately via
        `GET /app-runs`.

        **Filtering Options:**
        - `status`: Filter by execution status (in_progress, completed, failed, canceled)
        - `external_id`: Filter to runs you tagged with this reference id at creation.
          Use this to check whether you already started a run for a given item before
          starting another.

        **Pagination Parameters:**
        - `limit`: Maximum number of items to return (default: 20, max: 100)
        - `cursor`: Cursor for pagination (optional)

        **Response:**
        - `data`: List of run summaries with basic information
        - `has_more`: Indicates if there are more results available
        - `next_cursor`: Cursor for the next page of results

        **Use Case:** Monitor multiple executions and their status overview.
      operationId: list_runs_runs__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/FlowRunStatus'
          - type: 'null'
          title: Status
      - name: external_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of items to return
          default: 20
          title: Limit
        description: Maximum number of items to return
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Cursor for pagination (from next_cursor)
          title: Cursor
        description: Cursor for pagination (from next_cursor)
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPaginatedResponse_RunSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /runs/{run_id}:
    get:
      tags:
      - runs
      summary: Get Run
      description: |-
        Get detailed information about a specific agent execution run.

        This endpoint retrieves comprehensive information about an execution run,
        including real-time status, progress, inputs, and results when available.

        **Monitoring Workflow:**
        1. Create run via `POST /runs`
        2. Poll this endpoint to monitor progress
        3. If `awaiting_human_review` becomes `true`, inspect `pending_reviews`
           and resolve each via `POST /runs/{run_id}/reviews/{review_id}` to
           resume execution
        4. Stop polling when status becomes "completed", "failed", or "canceled"
        5. Extract results from the `results` array when status is "completed"

        **Progress Tracking:**
        - `status`: Current execution state
        - `progress`: Completion percentage (0.0 to 1.0)
        - `awaiting_human_review`: `true` when the run is paused on a human
          review node; `status` stays `in_progress` in this case
        - `pending_reviews`: List of review steps awaiting a decision
        - `created_at`: When execution started
        - `completed_at`: When execution finished (if applicable)

        **How to Retrieve Results:**

        When the run status becomes "completed", the `results` array contains the agent outputs.
        Call `GET /agents/{agent_id}` and examine the `outputs` array to understand what
        results to expect, then match results to outputs by `id`:

        **Text Results**: Use `value` directly as string.

        **Asset Results** (images/videos/audio): `value` is an array of asset UUIDs.
        Resolve each via `GET /assets/{id}` and fetch the `url` field.

        **Cost Information:**
        - `cost`: Total credits consumed by the execution

        **Error Handling:**
        - `error`: Error message if execution failed
        - `failure_reason`: Categorized failure cause

        **Error Codes:**
        - `404`: Run not found or not accessible
      operationId: get_run_runs__run_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - runs
      summary: Cancel Run
      description: |-
        Cancel an ongoing agent execution run.

        This endpoint allows you to cancel an execution that is currently running
        or pending. Once cancelled, the execution cannot be resumed.

        **Behavior:**
        - Only running or pending executions can be cancelled
        - Completed or failed executions cannot be cancelled
        - Cancellation may take a few seconds to take effect

        **Error Codes:**
        - `404`: Run not found or not accessible
      operationId: cancel_run_runs__run_id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /runs/{run_id}/reviews/{review_id}:
    post:
      tags:
      - runs
      summary: Submit Review
      description: |-
        Resolve a pending human review and resume an execution.

        When an agent includes a human review step, the run pauses on that node
        and `awaiting_human_review` becomes `true` on `GET /runs/{run_id}`. Each
        waiting step is listed in the run's `pending_reviews` array. Submit a
        decision here to resume.

        **Discovering pending reviews**

        1. Poll `GET /runs/{run_id}` until `awaiting_human_review` is `true`.
        2. Inspect the `pending_reviews` array. Use a review's `id` as
           `review_id` in this endpoint's path.
        3. The `proposed_output` field of each review is what the upstream node
           generated. Submit it back as `output` (optionally edited) to approve.

        **Decisions**

        - `approve`: continue execution. The `output` body field is required and
          must match the shape of `proposed_output`:
          - Image / video / audio reviews: `{"asset_ids": ["..."]}`.
          - Text-prompt reviews: `{"prompts": ["..."]}`.
          To discard items, approve with only the ones you want to keep — omitted
          items are dropped. At least one item must be kept (an empty `output` is
          rejected with `400`).
        - `retry`: re-run the upstream node(s) to produce a new candidate output.
          The run goes back to "in progress"; poll again to retrieve the new
          `pending_reviews` entry once it's ready. `output` is ignored.

        **Examples**

        Approve an image review using the proposed assets:
        ```json
        {
            "decision": "approve",
            "output": {
                "asset_ids": [
                    "asset-uuid-001",
                    "asset-uuid-002"
                ]
            }
        }
        ```

        Discard some of the proposed assets by approving with only the kept subset:
        ```json
        {"decision": "approve", "output": {"asset_ids": ["asset-uuid-001"]}}
        ```

        Retry to regenerate the upstream output:
        ```json
        {"decision": "retry"}
        ```

        **Error Codes:**
        - `400`: Missing `output`, or an empty `output` (nothing kept), when
          decision is `approve`.
        - `404`: Run not found, or no pending review with that ID on this run.
        - `409`: The review is no longer waiting (already submitted, or the run
          finished/failed/was canceled).
      operationId: submit_review_runs__run_id__reviews__review_id__post
      security:
      - APIKeyHeader: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: review_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Review Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitReviewRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app-runs/:
    post:
      tags:
      - app-runs
      summary: Create App Run
      description: |-
        Create and start a new app execution run.

        This endpoint launches the execution of an app with the provided inputs. The
        execution runs asynchronously, allowing you to monitor progress and retrieve
        results when complete.

        **Idempotency with `external_id`:** Optionally pass an `external_id` (e.g. your
        own order or job id). It is **unique per organization**: the first request with
        a given key starts the run; any later write reusing that key — including a
        dropped-response retry — is rejected with **`409 conflict`** instead of starting
        (and charging) a duplicate. To fetch the run a key already created, use
        `GET /app-runs?external_id=...`. The id is echoed on every app-run response.

        - Scope: per organization, across **all** runs (agent and app share the key
          space) and **all** statuses — a key, once used, stays used.
        - On `409`, do **not** keep retrying the create; `GET /app-runs?external_id=` to
          retrieve the existing run. To start a genuinely new run, use a new `external_id`.

        **How to Build Inputs:**

        1. **First, get app details**: Call `GET /apps/{app_id}` to retrieve the app
           configuration.
        2. **Examine the `inputs` array**: Each object defines what input the app expects:
           - `id`: Use this as the `id` in your input object
           - `type`: text, image, video, audio, brand, or file
           - `required`: whether the input is mandatory
           - `options` / `min_selections` / `max_selections`: constraints for fixed-set inputs

        **Text Inputs:**
        ```json
        {"id": "text_input_node_id", "value": "Your text content here"}
        ```

        **Asset Inputs** (image / video / audio / file):
        ```json
        {"id": "image_input_node_id", "value": {"asset_ids": ["uuid1", "uuid2"]}}
        ```
        Upload assets first via `POST /assets/upload` to get the UUIDs.

        **Example:**
        ```json
        {
            "app_id": "550e8400-e29b-41d4-a716-446655440000",
            "inputs": [
                {"id": "uuid-1", "value": "Create a marketing banner for a tech startup"}
            ]
        }
        ```

        **Curated contract:** only the inputs advertised by `GET /apps/{app_id}` are
        accepted. Unknown input ids, missing required inputs, and values that violate an
        input's `options` / `min_selections` / `max_selections` are rejected with `400`.
        The completed run's `results` contain only the app's curated outputs — never the
        underlying flow's internal nodes.

        **Response:**
        - AppRun object with execution details and initial status
        - Use `id` to monitor progress via `GET /app-runs/{run_id}`

        **Error Codes:**
        - `400`: Invalid input format, missing required inputs, or values outside constraints
        - `404`: App not found or not accessible
      operationId: create_app_run_app_runs__post
      security:
      - APIKeyHeader: []
      parameters:
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppRunCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppRun'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - app-runs
      summary: List App Runs
      description: |-
        List app execution runs with filtering options.

        This endpoint returns a paginated list of app execution runs with their current
        status and basic metadata. Agent runs are listed separately via `GET /runs`.

        **Filtering Options:**
        - `status`: Filter by execution status (in_progress, completed, failed, canceled)
        - `external_id`: Filter to runs you tagged with this reference id at creation.
          Use this to check whether you already started a run for a given item before
          starting another.

        **Pagination Parameters:**
        - `limit`: Maximum number of items to return (default: 20, max: 100)
        - `cursor`: Cursor for pagination (optional)

        **Response:**
        - `data`: List of app-run summaries with basic information
        - `has_more`: Indicates if there are more results available
        - `next_cursor`: Cursor for the next page of results
      operationId: list_app_runs_app_runs__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/FlowRunStatus'
          - type: 'null'
          title: Status
      - name: external_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of items to return
          default: 20
          title: Limit
        description: Maximum number of items to return
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Cursor for pagination (from next_cursor)
          title: Cursor
        description: Cursor for pagination (from next_cursor)
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPaginatedResponse_AppRunSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app-runs/{run_id}:
    get:
      tags:
      - app-runs
      summary: Get App Run
      description: |-
        Get detailed information about a specific app execution run.

        This endpoint retrieves comprehensive information about an app run, including
        real-time status, progress, inputs, and curated results when available.

        **Monitoring Workflow:**
        1. Create run via `POST /app-runs`
        2. Poll this endpoint to monitor progress
        3. Stop polling when status becomes "completed", "failed", or "canceled"
        4. Extract results from the `results` array when status is "completed"

        **How to Retrieve Results:**
        Call `GET /apps/{app_id}` and examine the `outputs` array, then match results to
        outputs by `id`. Asset results (images/videos/audio/files) are arrays of asset
        UUIDs — resolve each via `GET /assets/{id}` and fetch the `url` field.

        **Error Codes:**
        - `404`: Run not found or not accessible
      operationId: get_app_run_app_runs__run_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppRun'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - app-runs
      summary: Cancel App Run
      description: |-
        Cancel an ongoing app execution run.

        This endpoint allows you to cancel an execution that is currently running or
        pending. Once cancelled, the execution cannot be resumed.

        **Behavior:**
        - Only running or pending executions can be cancelled
        - Completed or failed executions cannot be cancelled
        - Cancellation may take a few seconds to take effect

        **Error Codes:**
        - `404`: Run not found or not accessible
      operationId: cancel_app_run_app_runs__run_id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: X-Organization-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Active organization ID for multi-org support
          title: X-Organization-Id
        description: Active organization ID for multi-org support
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Agent:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique agent identifier
        name:
          type: string
          title: Name
          description: Agent display name
        description:
          type: string
          title: Description
          description: Agent description and purpose
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Categorization tags for filtering
        inputs:
          items:
            $ref: '#/components/schemas/AgentInput'
          type: array
          title: Inputs
          description: All inputs for this agent. Use these IDs when creating a run; check the `required` flag on each input to determine which are mandatory
        outputs:
          items:
            $ref: '#/components/schemas/AgentOutput'
          type: array
          title: Outputs
          description: Expected outputs. Match these IDs in run results
        estimated_cost:
          type: integer
          title: Estimated Cost
          description: Estimated credit cost per execution
        has_human_review:
          type: boolean
          title: Has Human Review
          description: True when this agent includes a human review step that will pause execution until resolved via POST /runs/{run_id}/reviews/{review_id}. Poll GET /runs/{run_id} for `awaiting_human_review` while the run is in progress.
          default: false
      type: object
      required:
      - id
      - name
      - description
      - estimated_cost
      title: Agent
      description: Complete representation of an AI agent with its inputs, outputs, and cost.
      example:
        description: Generate marketing banners from a text prompt and logo
        estimated_cost: 50
        has_human_review: false
        id: 550e8400-e29b-41d4-a716-446655440000
        inputs:
        - description: Product description
          id: uuid-1
          required: true
          type: text_input
        - description: Company logo
          id: uuid-2
          required: false
          type: image_input
        name: Marketing Banner Generator
        outputs:
        - description: Generated banner
          id: uuid-3
          type: images
        tags:
        - marketing
        - image
    AgentInput:
      properties:
        id:
          type: string
          title: Id
          description: Node ID to use when providing this input
        type:
          $ref: '#/components/schemas/NodeType'
          description: 'Input type: text_input, image_input, video_input, file_input, etc.'
        description:
          type: string
          title: Description
          description: Human-readable description of this input
        required:
          type: boolean
          title: Required
          description: Whether this input must be provided when creating a run
          default: true
      type: object
      required:
      - id
      - type
      - description
      title: AgentInput
      description: Represents an input requirement for an agent.
    AgentOutput:
      properties:
        id:
          type: string
          title: Id
          description: Node ID to match in run results
        type:
          $ref: '#/components/schemas/DataType'
          description: 'Output data type: text, images, videos, files, audio, or data'
        description:
          type: string
          title: Description
          description: Human-readable description of this output
      type: object
      required:
      - id
      - type
      - description
      title: AgentOutput
      description: Represents an output produced by an agent.
    AgentSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique agent identifier
        name:
          type: string
          title: Name
          description: Agent display name
        description:
          type: string
          title: Description
          description: Agent description and purpose
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Categorization tags for filtering
        estimated_cost:
          type: integer
          title: Estimated Cost
          description: Estimated credit cost per execution
        visibility:
          $ref: '#/components/schemas/FlowVisibility'
          description: 'Visibility level: PRIVATE, SHARED, or PUBLIC'
        inputs:
          items:
            $ref: '#/components/schemas/AgentInput'
          type: array
          title: Inputs
          description: All inputs for this agent; check the `required` flag on each to determine which are mandatory
        has_human_review:
          type: boolean
          title: Has Human Review
          description: True when this agent includes a human review step that will pause execution until resolved via POST /runs/{run_id}/reviews/{review_id}. Poll GET /runs/{run_id} for `awaiting_human_review` while the run is in progress.
          default: false
      type: object
      required:
      - id
      - name
      - description
      - estimated_cost
      - visibility
      title: AgentSummary
      description: Lightweight agent summary for list views.
    App:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Stable app identifier
        name:
          type: string
          title: Name
          description: App display name
        description:
          type: string
          title: Description
          description: App description and purpose
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
          description: Public CDN URL for the app thumbnail image
        visibility:
          $ref: '#/components/schemas/FlowApplicationVisibility'
          description: 'Visibility level: private, workspace, shared, or public'
        inputs:
          items:
            $ref: '#/components/schemas/AppInput'
          type: array
          title: Inputs
          description: Required inputs for this app. Use these IDs when creating a run
        outputs:
          items:
            $ref: '#/components/schemas/AppOutput'
          type: array
          title: Outputs
          description: Expected outputs. Match these IDs in run results
        estimated_cost:
          type: integer
          title: Estimated Cost
          description: Estimated credit cost per execution
      type: object
      required:
      - id
      - name
      - description
      - visibility
      - estimated_cost
      title: App
      description: Complete representation of a runnable app with its inputs, outputs, and cost.
      example:
        avatar_url: https://cdn.example.com/apps/banner.png
        description: Generate marketing banners from a text prompt and logo
        estimated_cost: 50
        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
    AppInput:
      properties:
        id:
          type: string
          title: Id
          description: Node ID to use when providing this input
        type:
          $ref: '#/components/schemas/AppInputType'
          description: 'Input type: text, image, video, audio, brand, or file'
        name:
          type: string
          title: Name
          description: Display name of this input
        required:
          type: boolean
          title: Required
          description: Whether this input is mandatory
        options:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Options
          description: 'Allowed values when the input is a fixed set: label strings for text inputs, asset IDs for media inputs'
        min_selections:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Selections
          description: Minimum number of values the caller must provide for this input
        max_selections:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Selections
          description: Maximum number of values the caller may provide for this input
      type: object
      required:
      - id
      - type
      - name
      - required
      title: AppInput
      description: Represents an input requirement for an app.
    AppInputType:
      type: string
      enum:
      - text
      - image
      - video
      - audio
      - brand
      - file
      title: AppInputType
      description: Types of inputs an app can accept from a caller.
    AppOutput:
      properties:
        id:
          type: string
          title: Id
          description: Node ID to match in run results
        type:
          $ref: '#/components/schemas/DataType'
          description: 'Output data type: text, images, videos, files, audio, or data'
        description:
          type: string
          title: Description
          description: Human-readable description of this output
      type: object
      required:
      - id
      - type
      - description
      title: AppOutput
      description: Represents an output produced by an app.
    AppRun:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique run identifier
        app_id:
          type: string
          format: uuid
          title: App Id
          description: Stable ID of the app being executed
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Client-supplied reference id provided at creation, if any
        status:
          $ref: '#/components/schemas/FlowRunStatus'
          description: 'Current execution state: in_progress, completed, failed, or canceled'
        progress:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Progress
          description: Completion progress from 0.0 to 1.0
          default: 0.0
        current_node:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Node
          description: Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the run was created
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: When execution started
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When execution finished
        inputs:
          items:
            $ref: '#/components/schemas/RunInput'
          type: array
          title: Inputs
          description: Inputs provided for this run
        results:
          items:
            $ref: '#/components/schemas/RunResult'
          type: array
          title: Results
          description: Curated app outputs, populated when status is completed
        cost:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cost
          description: Total credits consumed by this run
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if the run failed
        failure_reason:
          anyOf:
          - $ref: '#/components/schemas/FailureReason'
          - type: 'null'
          description: Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed.
      type: object
      required:
      - id
      - app_id
      - status
      - created_at
      title: AppRun
      description: Complete representation of an app execution run.
      example:
        app_id: 550e8400-e29b-41d4-a716-446655440000
        created_at: '2026-04-15T10:00:00Z'
        current_node: image_generation
        external_id: order-4821
        id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        inputs:
        - id: text_input_1
          value: A futuristic city at sunset
        progress: 0.5
        results: []
        started_at: '2026-04-15T10:00:01Z'
        status: in_progress
    AppRunCreateRequest:
      properties:
        app_id:
          type: string
          format: uuid
          title: App Id
          description: Stable ID of the app to execute
        inputs:
          items:
            $ref: '#/components/schemas/RunInput'
          type: array
          title: Inputs
          description: Inputs for the app. Get required inputs from GET /apps/{id}
        external_id:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: External Id
          description: 'Optional client-supplied reference id (e.g. your order or job id, max 255 chars). Unique per organization: reusing one returns 409 conflict — so a dropped-response retry never creates a duplicate. Echoed on every app run and filterable via GET /app-runs?external_id= to fetch it. Use a new id per run.'
      type: object
      required:
      - app_id
      title: AppRunCreateRequest
      description: Request to create and start a new app execution run.
      example:
        app_id: 550e8400-e29b-41d4-a716-446655440000
        external_id: order-4821
        inputs:
        - id: text_input_1
          value: Create a marketing banner for a tech startup
    AppRunSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique run identifier
        app_id:
          type: string
          format: uuid
          title: App Id
          description: Stable ID of the app that was executed
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Client-supplied reference id provided at creation, if any
        status:
          $ref: '#/components/schemas/FlowRunStatus'
          description: Current execution state
        progress:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Progress
          description: Completion progress from 0.0 to 1.0
          default: 0.0
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the run was created
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: When execution started
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When execution finished
        cost:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cost
          description: Total credits consumed by this run
      type: object
      required:
      - id
      - app_id
      - status
      - created_at
      title: AppRunSummary
      description: Lightweight app-run summary for list views.
    AppSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Stable app identifier
        name:
          type: string
          title: Name
          description: App display name
        description:
          type: string
          title: Description
          description: App description and purpose
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
          description: Public CDN URL for the app thumbnail image
        visibility:
          $ref: '#/components/schemas/FlowApplicationVisibility'
          description: 'Visibility level: private, workspace, shared, or public'
        estimated_cost:
          type: integer
          title: Estimated Cost
          description: Estimated credit cost per execution
        inputs:
          items:
            $ref: '#/components/schemas/AppInput'
          type: array
          title: Inputs
          description: Required inputs for this app
      type: object
      required:
      - id
      - name
      - description
      - visibility
      - estimated_cost
      title: AppSummary
      description: Lightweight app summary for list views.
    Asset:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique asset identifier
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Client-supplied reference id provided at upload, if any
        asset_type:
          $ref: '#/components/schemas/AssetType'
          description: 'Asset role: reference (input), intermediate, or output'
        media_type:
          $ref: '#/components/schemas/MediaType'
          description: 'Media category: image, video, audio, or file'
        media_extension:
          $ref: '#/components/schemas/MediaExtension'
          description: 'File extension: png, jpg, mp4, pdf, etc.'
        visibility:
          $ref: '#/components/schemas/AssetVisibility'
          description: 'Visibility level: private, public, or shared'
        bookmarked:
          type: boolean
          title: Bookmarked
          description: Whether the asset is bookmarked
          default: false
        archived:
          type: boolean
          title: Archived
          description: Whether the asset is archived
          default: false
        downloaded:
          type: boolean
          title: Downloaded
          description: Whether the asset has been downloaded before
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the asset was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the asset was last modified
        url:
          type: string
          title: Url
          description: CDN URL for the asset (thumbnail/preview size)
        large_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Large Url
          description: CDN URL for the full-resolution version
        agent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Agent Id
          description: ID of the agent that produced this asset. Null for uploaded assets.
        run_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Run Id
          description: ID of the run that produced this asset. Null for uploaded assets.
        asset_metadata:
          additionalProperties:
            anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          type: object
          title: Asset Metadata
          description: 'Technical metadata: generation_model, aspect_ratio, duration, etc.'
        is_flow_output_sample:
          type: boolean
          title: Is Flow Output Sample
          description: Whether this asset is a sample output displayed on the agent card
          default: false
        blur_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Blur Hash
          description: BlurHash string for progressive image loading
      type: object
      required:
      - id
      - asset_type
      - media_type
      - media_extension
      - visibility
      - created_at
      - updated_at
      - url
      title: Asset
      description: Complete asset with all metadata.
    AssetSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique asset identifier
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Client-supplied reference id provided at upload, if any
        asset_type:
          $ref: '#/components/schemas/AssetType'
          description: 'Asset role: reference (input), intermediate, or output'
        media_type:
          $ref: '#/components/schemas/MediaType'
          description: 'Media category: image, video, audio, or file'
        media_extension:
          $ref: '#/components/schemas/MediaExtension'
          description: 'File extension: png, jpg, mp4, pdf, etc.'
        visibility:
          $ref: '#/components/schemas/AssetVisibility'
          description: 'Visibility level: private, public, or shared'
        bookmarked:
          type: boolean
          title: Bookmarked
          description: Whether the asset is bookmarked
          default: false
        archived:
          type: boolean
          title: Archived
          description: Whether the asset is archived
          default: false
        downloaded:
          type: boolean
          title: Downloaded
          description: Whether the asset has been downloaded before
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the asset was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the asset was last modified
        url:
          type: string
          title: Url
          description: CDN URL for the asset (thumbnail/preview size)
        large_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Large Url
          description: CDN URL for the full-resolution version
        agent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Agent Id
          description: ID of the agent that produced this asset. Null for uploaded assets.
        run_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Run Id
          description: ID of the run that produced this asset. Null for uploaded assets.
      type: object
      required:
      - id
      - asset_type
      - media_type
      - media_extension
      - visibility
      - created_at
      - updated_at
      - url
      title: AssetSummary
      description: Summary of an asset for list views.
    AssetType:
      type: string
      enum:
      - reference
      - intermediate
      - output
      title: AssetType
      description: Classification of assets by their role in workflows.
    AssetVisibility:
      type: string
      enum:
      - public
      - shared
      - private
      title: AssetVisibility
    Body_upload_asset_assets_upload__post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
        visibility:
          type: string
          title: Visibility
          description: Asset visibility level
          default: private
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
          description: Optional custom filename
        external_id:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: External Id
          description: Optional client-supplied reference id, unique per organization. Reusing one returns 409; fetch the existing asset via GET /assets?external_id=. Makes the upload safe to retry without creating a duplicate.
      type: object
      required:
      - file
      title: Body_upload_asset_assets_upload__post
    CursorPaginatedResponse_AgentSummary_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AgentSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - data
      - has_more
      title: CursorPaginatedResponse[AgentSummary]
    CursorPaginatedResponse_AppRunSummary_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AppRunSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - data
      - has_more
      title: CursorPaginatedResponse[AppRunSummary]
    CursorPaginatedResponse_AppSummary_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AppSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - data
      - has_more
      title: CursorPaginatedResponse[AppSummary]
    CursorPaginatedResponse_AssetSummary_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AssetSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - data
      - has_more
      title: CursorPaginatedResponse[AssetSummary]
    CursorPaginatedResponse_RunSummary_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/RunSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - data
      - has_more
      title: CursorPaginatedResponse[RunSummary]
    DataType:
      type: string
      enum:
      - text
      - images
      - videos
      - files
      - audio
      - data
      title: DataType
      description: Types of data that agents can accept as input or produce as output.
    FailureReason:
      type: string
      enum:
      - timeout
      - content_policy
      - insufficient_credits
      - invalid_input
      - provider_error
      - provider_auth_required
      - canceled
      - unknown
      title: FailureReason
      description: |-
        Stable, client-facing categories for why a run failed. A curated public
        view over the internal `NodeFailureReason`; internal-only causes collapse to
        `unknown` so the public contract stays stable as internals change.
    FlowApplicationVisibility:
      type: string
      enum:
      - private
      - workspace
      - shared
      - public
      title: FlowApplicationVisibility
      description: Visibility levels for flow applications.
    FlowRunStatus:
      type: string
      enum:
      - in_progress
      - completed
      - failed
      - canceled
      title: FlowRunStatus
      description: Execution status of a workflow run.
    FlowVisibility:
      type: string
      enum:
      - public
      - shared
      - private
      title: FlowVisibility
      description: Visibility levels for workflows.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MediaExtension:
      type: string
      enum:
      - png
      - jpg
      - jpeg
      - svg
      - heic
      - heif
      - avif
      - webp
      - mp4
      - wav
      - mp3
      - mov
      - webm
      - pdf
      - docx
      - csv
      - txt
      - json
      - md
      - ttf
      - otf
      - woff
      - woff2
      title: MediaExtension
    MediaType:
      type: string
      enum:
      - image
      - video
      - audio
      - file
      title: MediaType
      description: Primary media categories for assets.
    NodeType:
      type: string
      enum:
      - text_input
      - image_input
      - file_input
      - video_input
      - audio_input
      - brand_system_input
      - llm
      - image_generation
      - video_generation
      - text_to_speech
      - screen_mockup
      - remove_background
      - upscale
      - upscale_video
      - video_background_removal
      - extract_video_frame
      - image_generation_lora
      - change_aspect_ratio
      - meta_ads_extractor
      - image_edit
      - vectorize
      - image_erase
      - linkedin_ads_extractor
      - instagram_posts_extractor
      - linkedin_posts_extractor
      - human_review
      - match_brand_colors
      - tiktok_extractor
      - add_logo
      - video_subtitle
      - video_concat
      - video_add_sound
      - generic_fal
      - comment
      - group
      - composer
      - googledrive_find_file
      - googledrive_upload_file
      - prompt_concatenate
      - text_split
      - list_selector
      - video_edit
      - router
      - camera_angle
      - rename_asset
      - music_generation
      - merge_audio_video
      - trim_speed
      - extract_audio
      - remove_audio
      - isolate_sound
      - clone_voice
      - translate_audio
      - translate_video
      - transcribe
      title: NodeType
    PendingReview:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Identifier of the pending review. Use this as `review_id` when calling POST /runs/{run_id}/reviews/{review_id} to resume execution.
        node_id:
          type: string
          title: Node Id
          description: ID of the human review node inside the agent definition
        reviewed_node_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Reviewed Node Type
          description: Type of the upstream node whose output is being reviewed (e.g. image_generation, llm). May be null for legacy reviews.
        reviewed_output_type:
          anyOf:
          - $ref: '#/components/schemas/DataType'
          - type: 'null'
          description: Business-friendly type of the output under review (text, images, videos, audio, files, data).
        proposed_output:
          anyOf:
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          - type: string
          - type: 'null'
          title: Proposed Output
          description: Output produced by the upstream node(s) that is being reviewed. Submit this back (optionally edited) as `output` when approving. To discard items, submit only the ones you want to keep — omitted items are dropped. At least one item must be kept.
        can_edit_outputs:
          type: boolean
          title: Can Edit Outputs
          description: Whether the agent definition allows editing the proposed output before approval.
          default: false
        can_generate_more:
          type: boolean
          title: Can Generate More
          description: Whether the agent definition allows regenerating the upstream output (decision=retry).
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the review was opened
      type: object
      required:
      - id
      - node_id
      - created_at
      title: PendingReview
      description: A human review step that is currently waiting for a decision.
      example:
        can_edit_outputs: true
        can_generate_more: true
        created_at: '2026-04-15T10:01:30Z'
        id: 11111111-2222-3333-4444-555555555555
        node_id: human_review_node_1
        proposed_output:
          asset_ids:
          - asset-uuid-001
          - asset-uuid-002
        reviewed_node_type: image_generation
        reviewed_output_type: images
    ReviewDecision:
      type: string
      enum:
      - approve
      - retry
      title: ReviewDecision
      description: Possible decisions when responding to a pending human review.
    Run:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique run identifier
        agent_id:
          type: string
          format: uuid
          title: Agent Id
          description: ID of the agent being executed
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Client-supplied reference id provided at creation, if any
        status:
          $ref: '#/components/schemas/FlowRunStatus'
          description: 'Current execution state: in_progress, completed, failed, or canceled'
        progress:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Progress
          description: Completion progress from 0.0 to 1.0
          default: 0.0
        current_node:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Node
          description: Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress
        awaiting_human_review:
          type: boolean
          title: Awaiting Human Review
          description: True when the run has paused on one or more human review nodes and is waiting for a decision via POST /runs/{run_id}/reviews/{review_id}. While true, `status` remains `in_progress`.
          default: false
        pending_reviews:
          items:
            $ref: '#/components/schemas/PendingReview'
          type: array
          title: Pending Reviews
          description: Human review steps currently waiting for a decision. Empty unless `awaiting_human_review` is true.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the run was created
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: When execution started
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When execution finished
        inputs:
          items:
            $ref: '#/components/schemas/RunInput'
          type: array
          title: Inputs
          description: Inputs provided for this run
        results:
          items:
            $ref: '#/components/schemas/RunResult'
          type: array
          title: Results
          description: Output results, populated when status is completed
        cost:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cost
          description: Total credits consumed by this run
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if the run failed
        failure_reason:
          anyOf:
          - $ref: '#/components/schemas/FailureReason'
          - type: 'null'
          description: Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed.
      type: object
      required:
      - id
      - agent_id
      - status
      - created_at
      title: Run
      description: Complete representation of an agent execution run.
      example:
        agent_id: 550e8400-e29b-41d4-a716-446655440000
        awaiting_human_review: false
        created_at: '2026-04-15T10:00:00Z'
        current_node: image_generation
        external_id: order-4821
        id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        inputs:
        - id: text_input_1
          value: A futuristic city at sunset
        pending_reviews: []
        progress: 0.5
        results: []
        started_at: '2026-04-15T10:00:01Z'
        status: in_progress
    RunCreateRequest:
      properties:
        agent_id:
          type: string
          format: uuid
          title: Agent Id
          description: ID of the agent to execute
        inputs:
          items:
            $ref: '#/components/schemas/RunInput'
          type: array
          title: Inputs
          description: Inputs for the agent. Get required inputs from GET /agents/{id}
        external_id:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: External Id
          description: 'Optional client-supplied reference id (e.g. your order or job id, max 255 chars). Unique per organization: reusing one returns 409 conflict — so a dropped-response retry never creates a duplicate. Echoed on every run and filterable via GET /runs?external_id= to fetch it. Use a new id per run.'
      type: object
      required:
      - agent_id
      title: RunCreateRequest
      description: Request to create and start a new agent execution run.
      example:
        agent_id: 550e8400-e29b-41d4-a716-446655440000
        external_id: order-4821
        inputs:
        - id: text_input_1
          value: Create a marketing banner for a tech startup
    RunInput:
      properties:
        id:
          type: string
          title: Id
          description: Node ID that this input targets
        value:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          title: Value
          description: 'Input value: plain text string for text inputs, or {"asset_ids": ["uuid"]} for asset inputs'
      type: object
      required:
      - id
      - value
      title: RunInput
      description: |-
        Represents an input provided to a run.

        Shared by agent runs and app runs: both pipelines accept the same wire shape.
      examples:
      - id: text_input_1
        value: A futuristic city at sunset
      - id: image_input_1
        value:
          asset_ids:
          - 550e8400-e29b-41d4-a716-446655440000
    RunResult:
      properties:
        id:
          type: string
          title: Id
          description: Node ID that produced this result
        type:
          $ref: '#/components/schemas/DataType'
          description: Type of the result data
        value:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Value
          description: 'Result content: text string, list of asset UUIDs, or structured data'
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Human-readable description of the result
      type: object
      required:
      - id
      - type
      title: RunResult
      description: |-
        Represents a result produced by a run.

        Shared by agent runs and app runs: both pipelines emit the same wire shape.
    RunSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique run identifier
        agent_id:
          type: string
          format: uuid
          title: Agent Id
          description: ID of the agent that was executed
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Client-supplied reference id provided at creation, if any
        status:
          $ref: '#/components/schemas/FlowRunStatus'
          description: Current execution state
        progress:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Progress
          description: Completion progress from 0.0 to 1.0
          default: 0.0
        awaiting_human_review:
          type: boolean
          title: Awaiting Human Review
          description: True when the run has paused on one or more human review nodes. Fetch GET /runs/{run_id} to inspect pending reviews.
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the run was created
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: When execution started
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When execution finished
        cost:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cost
          description: Total credits consumed by this run
      type: object
      required:
      - id
      - agent_id
      - status
      - created_at
      title: RunSummary
      description: Lightweight run summary for list views.
    SubmitReviewRequest:
      properties:
        decision:
          $ref: '#/components/schemas/ReviewDecision'
          description: '`approve` resumes execution using the (optionally edited) output. `retry` re-runs the upstream node(s) to produce a new candidate output.'
        output:
          anyOf:
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          - type: string
          - type: 'null'
          title: Output
          description: 'Output to use when continuing execution. Required when decision is `approve`. Ignored when decision is `retry`. Must match the shape of `proposed_output` ({"asset_ids": [...]} for image/video/audio reviews, or {"prompts": [...]} for text-prompt reviews). To discard items, submit only the ones you want to keep; the rest are dropped. At least one item is required — an empty output is rejected.'
      type: object
      required:
      - decision
      title: SubmitReviewRequest
      description: Request to resolve a pending human review.
      examples:
      - decision: approve
        output:
          asset_ids:
          - asset-uuid-001
          - asset-uuid-002
      - decision: approve
        output:
          asset_ids:
          - asset-uuid-001
      - decision: retry
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Cognito JWT Bearer token
servers:
- url: https://api.pletor.ai/api/public/v1
  description: Production
tags:
- name: agents
  x-page-title: Agents
  x-page-icon: robot
  x-page-description: Agents represent specific AI-powered capabilities — on-brand photo generation, UGC video generation, static ads generation, and more. Use these endpoints to discover available agents and inspect their required inputs and expected outputs.
  description: Discover AI agents and inspect their input requirements and output types.
- name: apps
  x-page-title: Apps
  x-page-icon: grid-2
  x-page-description: 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`.
  description: Discover and inspect runnable apps built on flows.
- name: runs
  x-page-title: Runs
  x-page-icon: circle-play
  x-page-description: 'Runs are executions of agents. The typical workflow: discover an agent, inspect its required inputs, upload any necessary assets, create a run with matching inputs, poll its status, and retrieve generated outputs once complete. App executions live under App Runs.'
  description: Create, monitor, and cancel agent executions.
- name: app-runs
  x-page-title: App Runs
  x-page-icon: circle-play
  x-page-description: 'App runs are executions of apps. The workflow mirrors agent runs: discover an app, inspect its required inputs, upload any necessary assets, create a run with matching inputs, poll its status, and retrieve the app''s curated outputs once complete.'
  description: Create, monitor, and cancel app executions.
- name: assets
  x-page-title: Assets
  x-page-icon: folder-open
  x-page-description: Assets are files you upload or that are generated through the API. They serve as inputs for agent executions (product photos, logos) and outputs produced by agents (images, videos). Use these endpoints to upload, retrieve metadata, and download files across the full asset lifecycle.
  description: Upload, retrieve, and download files used as inputs or generated as outputs.
security:
- ApiKeyAuth: []
- BearerAuth: []
