> For the complete documentation index, see [llms.txt](https://docs.pletor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pletor.ai/documentation/api-reference/models.md). # Models ## The App object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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":"Inputs this app accepts, in display order, each marked required or optional. Use these IDs when creating a run. Brand context is resolved from the app's flow and is never an input"},"outputs":{"items":{"$ref":"#/components/schemas/AppOutput"},"type":"array","title":"Outputs","description":"Expected outputs. Match these IDs in run results"},"settings":{"items":{"$ref":"#/components/schemas/AppSetting"},"type":"array","title":"Settings","description":"Generation settings a run may change, in display order"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution at the default settings, computed when the app's flow version was saved. 0 when no estimate is available"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when this app includes a human review step that will pause a run until a decision is submitted via POST /app-runs/{run_id}/reviews/{review_id}. Poll GET /app-runs/{run_id} for `awaiting_human_review` while the run is in progress.","default":false}},"type":"object","required":["id","name","description","visibility","estimated_cost"],"title":"App","description":"Complete representation of a runnable app with its inputs, outputs, and cost."},"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"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 or file. Text inputs take a string (or a list of strings); the others take {\"asset_ids\": [...]}"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory. Omitting a required input is rejected with 400"},"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. Values outside the set are rejected with 400 unless the app lets callers supply their own. Null for free-form inputs, and for media inputs when the caller is outside the app's organization"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input. Null when there is no minimum"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input. Null when there is no cap"}},"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","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, audio, or data"},"description":{"type":"string","title":"Description","description":"Human-readable description of this output"},"optional":{"type":"boolean","title":"Optional","description":"Whether a run may leave this output out through `outputs`","default":false}},"type":"object","required":["id","type","description"],"title":"AppOutput","description":"Represents an output produced by an app."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Kind of content an output, run result or review carries. In run results,\n`text` values are text, `images` / `videos` / `audio` values are asset IDs\nto download, and `data` values are structured JSON."},"AppSetting":{"properties":{"id":{"type":"string","title":"Id","description":"Setting ID to use in a run's `settings`"},"name":{"type":"string","title":"Name","description":"Display name of this setting"},"allowed":{"items":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"},{"type":"number"}]},"type":"array","title":"Allowed","description":"Values this setting accepts; anything else is rejected with 400. Some combinations of settings can still be rejected with 400 when a step cannot run them together (e.g. an aspect ratio the chosen model lacks)"},"default":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"},{"type":"number"}],"title":"Default","description":"Value used when the run omits it"}},"type":"object","required":["id","name","allowed","default"],"title":"AppSetting","description":"A generation setting (model, aspect ratio, duration…) a caller may change."}}}} ``` ## The AppInput object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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 or file. Text inputs take a string (or a list of strings); the others take {\"asset_ids\": [...]}"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory. Omitting a required input is rejected with 400"},"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. Values outside the set are rejected with 400 unless the app lets callers supply their own. Null for free-form inputs, and for media inputs when the caller is outside the app's organization"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input. Null when there is no minimum"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input. Null when there is no cap"}},"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","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."}}}} ``` ## The AppInputType object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"AppInputType":{"type":"string","enum":["text","image","video","audio","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."}}}} ``` ## The AppOutput object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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, audio, or data"},"description":{"type":"string","title":"Description","description":"Human-readable description of this output"},"optional":{"type":"boolean","title":"Optional","description":"Whether a run may leave this output out through `outputs`","default":false}},"type":"object","required":["id","type","description"],"title":"AppOutput","description":"Represents an output produced by an app."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Kind of content an output, run result or review carries. In run results,\n`text` values are text, `images` / `videos` / `audio` values are asset IDs\nto download, and `data` values are structured JSON."}}}} ``` ## The AppRun object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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. A run starts in_progress and ends in exactly one of the others"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Fraction of the run's node executions that have completed, from 0.0 to 1.0. 1.0 once completed; 0.0 once failed or canceled","default":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 /app-runs/{run_id}/reviews/{review_id}. While true, `status` remains `in_progress`. A review left without a decision for 1 week fails the run.","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 (completed, failed or canceled). Null while in_progress"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs provided for this run. The create response echoes them as sent; later reads return them as stored — text values as a list of strings, asset values as {\"asset_ids\": [...]}"},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"Outputs of the app's curated output nodes — never the flow's internal nodes. Each entry appears once its node has produced output, so the list fills in while in_progress and is complete once status is completed. After a human review `retry`, only the latest attempt is kept"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed by this run so far, summed over its node executions. Null before any node has run"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the run failed or was canceled"},"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 or canceled."}},"type":"object","required":["id","app_id","status","created_at"],"title":"AppRun","description":"Complete representation of an app execution run."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"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} — or POST /app-runs/{run_id}/reviews/{review_id} for an app run — to resume execution. A `retry` keeps the same id: the review stays listed while the upstream output regenerates."},"node_id":{"type":"string","title":"Node Id","description":"ID of the human review node inside the flow 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). Null when that node has no execution record — input nodes (text/image/video/audio/file inputs) never do."},"reviewed_output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Kind of output under review (text, images, videos, audio, data). Null when `reviewed_node_type` is null or has no public output mapping."},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"Output of the reviewed upstream node (the first one, when the review covers several), in that node's own shape — e.g. {\"asset_ids\": [...]} for media. Submit it 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. Null when there is nothing to show: the review covers only input nodes, or the upstream node is still regenerating after a `retry`."},"can_edit_outputs":{"type":"boolean","title":"Can Edit Outputs","description":"Always true: every review step lets reviewers edit the proposed output.","default":true},"can_generate_more":{"type":"boolean","title":"Can Generate More","description":"Whether the review step offers regenerating the upstream output (decision `retry`). Always false when the review only covers input nodes. Informational: the API does not enforce it.","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.\n\nShared by runs and app runs: both pause on human review nodes the same way."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Kind of content an output, run result or review carries. In run results,\n`text` values are text, `images` / `videos` / `audio` values are asset IDs\nto download, and `data` values are structured JSON."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the input this value fills, as listed in the `inputs` of the flow or app"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value. Text inputs take a string, or a list of strings. Image, video, audio and file inputs take {\"asset_ids\": [\"uuid\", ...]} (a bare list of asset IDs is also accepted). Upload files first via POST /assets/upload. When read back from a stored run, text values come back as a list of strings and asset values as {\"asset_ids\": [...]}."}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by runs and app runs: both pipelines accept the same wire shape."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the node that produced this result. Match it against the `id` of an entry in the flow's or app's `outputs`."},"type":{"$ref":"#/components/schemas/DataType","description":"Kind of result: `text`, `images`, `videos`, `audio`, or `data` (structured output, and any node type without a more specific mapping)"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content. `text`: a string, or a list of strings when the node produced several. `images` / `videos` / `audio`: a list of asset IDs — resolve each via GET /assets/{id}. `data`: the node's raw output object."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Generic label for the result kind (e.g. \"Generated images\")"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by runs and app runs: both pipelines emit the same wire shape."},"FailureReason":{"type":"string","enum":["timeout","content_policy","insufficient_credits","invalid_input","provider_error","provider_auth_required","canceled","unknown"],"title":"FailureReason","description":"Stable category for why a run failed: `timeout` (a step ran out of time),\n`content_policy` (blocked by content moderation), `insufficient_credits`\n(credit or quota exhausted), `invalid_input` (an input, or an uploaded file,\ncould not be used), `provider_error` (an upstream AI provider failed),\n`provider_auth_required` (a connected provider account is missing or expired\nand must be reconnected), `canceled` (the run was canceled), `unknown` (any\ncause without a category of its own)."}}}} ``` ## The AppRunCreateRequest object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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, keyed by the `id`s listed in GET /apps/{id}. Every required input must be present; unknown ids are rejected with 400"},"settings":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"},{"type":"number"}]},"type":"object","title":"Settings","description":"Setting values keyed by the setting `id`s listed in GET /apps/{id}. Omitted settings use their default; unknown ids and values outside `allowed` are rejected with 400"},"outputs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Outputs","description":"Output ids to produce, from the `outputs` listed in GET /apps/{id}. Omitted produces every output. Required outputs are always produced; leaving an optional one out skips the steps only it needs, and their cost. Unknown ids are rejected with 400"},"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."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the input this value fills, as listed in the `inputs` of the flow or app"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value. Text inputs take a string, or a list of strings. Image, video, audio and file inputs take {\"asset_ids\": [\"uuid\", ...]} (a bare list of asset IDs is also accepted). Upload files first via POST /assets/upload. When read back from a stored run, text values come back as a list of strings and asset values as {\"asset_ids\": [...]}."}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by runs and app runs: both pipelines accept the same wire shape."}}}} ``` ## The AppRunSummary object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Fraction of the run's node executions that have completed, from 0.0 to 1.0. 1.0 once completed; 0.0 once failed or canceled","default":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 /app-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 (completed, failed or canceled). Null while in_progress"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed by this run so far, summed over its node executions. Null before any node has run"}},"type":"object","required":["id","app_id","status","created_at"],"title":"AppRunSummary","description":"Lightweight app-run summary for list views."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."}}}} ``` ## The AppSetting object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"AppSetting":{"properties":{"id":{"type":"string","title":"Id","description":"Setting ID to use in a run's `settings`"},"name":{"type":"string","title":"Name","description":"Display name of this setting"},"allowed":{"items":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"},{"type":"number"}]},"type":"array","title":"Allowed","description":"Values this setting accepts; anything else is rejected with 400. Some combinations of settings can still be rejected with 400 when a step cannot run them together (e.g. an aspect ratio the chosen model lacks)"},"default":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"},{"type":"number"}],"title":"Default","description":"Value used when the run omits it"}},"type":"object","required":["id","name","allowed","default"],"title":"AppSetting","description":"A generation setting (model, aspect ratio, duration…) a caller may change."}}}} ``` ## The AppSummary object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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. 0 when no estimate is available"},"inputs":{"items":{"$ref":"#/components/schemas/AppInput"},"type":"array","title":"Inputs","description":"Inputs this app accepts, in display order, each marked required or optional"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when a run of this app pauses on a human review step. Fetch GET /apps/{app_id} for the full contract.","default":false}},"type":"object","required":["id","name","description","visibility","estimated_cost"],"title":"AppSummary","description":"Lightweight app summary for list views."},"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"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 or file. Text inputs take a string (or a list of strings); the others take {\"asset_ids\": [...]}"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory. Omitting a required input is rejected with 400"},"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. Values outside the set are rejected with 400 unless the app lets callers supply their own. Null for free-form inputs, and for media inputs when the caller is outside the app's organization"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input. Null when there is no minimum"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input. Null when there is no cap"}},"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","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."}}}} ``` ## The Asset object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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 (a file you uploaded), intermediate (produced mid-run), or output (a run's final result)"},"media_type":{"$ref":"#/components/schemas/MediaType","description":"Media category: image, video, audio, file, or design (an HTML artboard, downloadable as a zip or a rendered image)"},"media_extension":{"$ref":"#/components/schemas/MediaExtension","description":"File extension of the stored file: png, jpg, mp4, pdf, etc."},"visibility":{"$ref":"#/components/schemas/AssetVisibility","description":"Visibility level: private (your organization only), or public / shared (readable by any authenticated caller that has the asset ID)"},"bookmarked":{"type":"boolean","title":"Bookmarked","description":"Whether the asset is bookmarked","default":false},"archived":{"type":"boolean","title":"Archived","description":"Whether the asset is archived. Also true for a deleted asset, which `GET /assets/{asset_id}` still returns","default":false},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tag names applied to this asset, in their stored casing, sorted alphabetically (case-insensitive)"},"downloaded":{"type":"boolean","title":"Downloaded","description":"Whether a download link has ever been requested for this asset, through the API or the Pletor web app","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":"Signed URL to the full asset file. It expires (at most one hour after the response), so re-fetch the asset instead of storing it. While a generated asset is still processing, this is the provider's own short-lived URL"},"large_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Large Url","description":"Stable CDN URL for a preview: a WebP rendition fitting 700x700 for images, a PNG poster frame for videos. Null for audio and other files. While an asset is still processing it is the provider's short-lived URL for images and null for videos"},"flow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Flow Id","description":"ID of the flow 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. Keys vary by media type and origin"},"is_flow_output_sample":{"type":"boolean","title":"Is Flow Output Sample","description":"Whether this asset is a sample output displayed on the flow card","default":false},"blur_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blur Hash","description":"BlurHash string for progressive image loading. Null until processing completes, and for audio and other files"},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","asset_type","media_type","media_extension","visibility","created_at","updated_at","url","agent_id"],"title":"Asset","description":"Complete asset with all metadata."},"AssetType":{"type":"string","enum":["reference","intermediate","output"],"title":"AssetType","description":"Classification of assets by their role in workflows."},"MediaType":{"type":"string","enum":["image","video","audio","file","design"],"title":"MediaType","description":"Primary media categories for assets."},"MediaExtension":{"type":"string","enum":["png","jpg","jpeg","svg","heic","heif","avif","webp","gif","mp4","wav","mp3","mov","webm","pdf","docx","xlsx","pptx","csv","txt","json","md","html","css","js","xml","yaml","yml","zip","ai","eps","ttf","otf","woff","woff2"],"title":"MediaExtension"},"AssetVisibility":{"type":"string","enum":["public","shared","private"],"title":"AssetVisibility"}}}} ``` ## The AssetAddTagsRequest object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"AssetAddTagsRequest":{"properties":{"tags":{"items":{"type":"string","maxLength":50,"minLength":1},"type":"array","minItems":1,"title":"Tags","description":"Tag names to add (at least one; 1-50 characters each after trimming surrounding whitespace; case-insensitive). Tags that don't exist yet in your organization are created automatically; tags already on the asset are skipped."}},"type":"object","required":["tags"],"title":"AssetAddTagsRequest","description":"Tag names to add to an asset."}}}} ``` ## The AssetSummary object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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 (a file you uploaded), intermediate (produced mid-run), or output (a run's final result)"},"media_type":{"$ref":"#/components/schemas/MediaType","description":"Media category: image, video, audio, file, or design (an HTML artboard, downloadable as a zip or a rendered image)"},"media_extension":{"$ref":"#/components/schemas/MediaExtension","description":"File extension of the stored file: png, jpg, mp4, pdf, etc."},"visibility":{"$ref":"#/components/schemas/AssetVisibility","description":"Visibility level: private (your organization only), or public / shared (readable by any authenticated caller that has the asset ID)"},"bookmarked":{"type":"boolean","title":"Bookmarked","description":"Whether the asset is bookmarked","default":false},"archived":{"type":"boolean","title":"Archived","description":"Whether the asset is archived. Also true for a deleted asset, which `GET /assets/{asset_id}` still returns","default":false},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tag names applied to this asset, in their stored casing, sorted alphabetically (case-insensitive)"},"downloaded":{"type":"boolean","title":"Downloaded","description":"Whether a download link has ever been requested for this asset, through the API or the Pletor web app","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":"Signed URL to the full asset file. It expires (at most one hour after the response), so re-fetch the asset instead of storing it. While a generated asset is still processing, this is the provider's own short-lived URL"},"large_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Large Url","description":"Stable CDN URL for a preview: a WebP rendition fitting 700x700 for images, a PNG poster frame for videos. Null for audio and other files. While an asset is still processing it is the provider's short-lived URL for images and null for videos"},"flow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Flow Id","description":"ID of the flow 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."},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","asset_type","media_type","media_extension","visibility","created_at","updated_at","url","agent_id"],"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."},"MediaType":{"type":"string","enum":["image","video","audio","file","design"],"title":"MediaType","description":"Primary media categories for assets."},"MediaExtension":{"type":"string","enum":["png","jpg","jpeg","svg","heic","heif","avif","webp","gif","mp4","wav","mp3","mov","webm","pdf","docx","xlsx","pptx","csv","txt","json","md","html","css","js","xml","yaml","yml","zip","ai","eps","ttf","otf","woff","woff2"],"title":"MediaExtension"},"AssetVisibility":{"type":"string","enum":["public","shared","private"],"title":"AssetVisibility"}}}} ``` ## The AssetType object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"AssetType":{"type":"string","enum":["reference","intermediate","output"],"title":"AssetType","description":"Classification of assets by their role in workflows."}}}} ``` ## The AssetUpdateRequest object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"AssetUpdateRequest":{"properties":{"bookmarked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Bookmarked","description":"Set to true to bookmark the asset, false to remove the bookmark. Omit or send null to leave it unchanged"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Archived","description":"Set to true to archive the asset, false to unarchive it. Omit or send null to leave it unchanged. Archiving an asset still being processed returns 409"}},"type":"object","title":"AssetUpdateRequest","description":"Fields an API client can update on an asset. Omitted fields are unchanged."}}}} ``` ## The AssetVisibility object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"AssetVisibility":{"type":"string","enum":["public","shared","private"],"title":"AssetVisibility"}}}} ``` ## The Body\_upload\_asset\_assets\_upload\_\_post object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"Body_upload_asset_assets_upload__post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The file to upload. Its type is taken from this part's `Content-Type` header, which must name a supported type; `application/octet-stream` or a missing type is rejected with 400."},"visibility":{"type":"string","title":"Visibility","description":"Requested visibility. Uploads are currently always stored as `private`, whatever this value is.","default":"private"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"Display filename, used as the name of the downloaded file. Defaults to the uploaded file's own name."},"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"}}}} ``` ## The CursorPaginatedResponse\_AppRunSummary\_ object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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]"},"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: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Fraction of the run's node executions that have completed, from 0.0 to 1.0. 1.0 once completed; 0.0 once failed or canceled","default":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 /app-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 (completed, failed or canceled). Null while in_progress"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed by this run so far, summed over its node executions. Null before any node has run"}},"type":"object","required":["id","app_id","status","created_at"],"title":"AppRunSummary","description":"Lightweight app-run summary for list views."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."}}}} ``` ## The CursorPaginatedResponse\_AppSummary\_ object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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]"},"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. 0 when no estimate is available"},"inputs":{"items":{"$ref":"#/components/schemas/AppInput"},"type":"array","title":"Inputs","description":"Inputs this app accepts, in display order, each marked required or optional"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when a run of this app pauses on a human review step. Fetch GET /apps/{app_id} for the full contract.","default":false}},"type":"object","required":["id","name","description","visibility","estimated_cost"],"title":"AppSummary","description":"Lightweight app summary for list views."},"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"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 or file. Text inputs take a string (or a list of strings); the others take {\"asset_ids\": [...]}"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory. Omitting a required input is rejected with 400"},"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. Values outside the set are rejected with 400 unless the app lets callers supply their own. Null for free-form inputs, and for media inputs when the caller is outside the app's organization"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input. Null when there is no minimum"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input. Null when there is no cap"}},"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","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."}}}} ``` ## The CursorPaginatedResponse\_AssetSummary\_ object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"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]"},"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 (a file you uploaded), intermediate (produced mid-run), or output (a run's final result)"},"media_type":{"$ref":"#/components/schemas/MediaType","description":"Media category: image, video, audio, file, or design (an HTML artboard, downloadable as a zip or a rendered image)"},"media_extension":{"$ref":"#/components/schemas/MediaExtension","description":"File extension of the stored file: png, jpg, mp4, pdf, etc."},"visibility":{"$ref":"#/components/schemas/AssetVisibility","description":"Visibility level: private (your organization only), or public / shared (readable by any authenticated caller that has the asset ID)"},"bookmarked":{"type":"boolean","title":"Bookmarked","description":"Whether the asset is bookmarked","default":false},"archived":{"type":"boolean","title":"Archived","description":"Whether the asset is archived. Also true for a deleted asset, which `GET /assets/{asset_id}` still returns","default":false},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tag names applied to this asset, in their stored casing, sorted alphabetically (case-insensitive)"},"downloaded":{"type":"boolean","title":"Downloaded","description":"Whether a download link has ever been requested for this asset, through the API or the Pletor web app","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":"Signed URL to the full asset file. It expires (at most one hour after the response), so re-fetch the asset instead of storing it. While a generated asset is still processing, this is the provider's own short-lived URL"},"large_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Large Url","description":"Stable CDN URL for a preview: a WebP rendition fitting 700x700 for images, a PNG poster frame for videos. Null for audio and other files. While an asset is still processing it is the provider's short-lived URL for images and null for videos"},"flow_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Flow Id","description":"ID of the flow 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."},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","asset_type","media_type","media_extension","visibility","created_at","updated_at","url","agent_id"],"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."},"MediaType":{"type":"string","enum":["image","video","audio","file","design"],"title":"MediaType","description":"Primary media categories for assets."},"MediaExtension":{"type":"string","enum":["png","jpg","jpeg","svg","heic","heif","avif","webp","gif","mp4","wav","mp3","mov","webm","pdf","docx","xlsx","pptx","csv","txt","json","md","html","css","js","xml","yaml","yml","zip","ai","eps","ttf","otf","woff","woff2"],"title":"MediaExtension"},"AssetVisibility":{"type":"string","enum":["public","shared","private"],"title":"AssetVisibility"}}}} ``` ## The CursorPaginatedResponse\_FlowSummary\_ object ```json {"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"components":{"schemas":{"CursorPaginatedResponse_FlowSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FlowSummary"},"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[FlowSummary]"},"FlowSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique flow identifier"},"name":{"type":"string","title":"Name","description":"Flow display name"},"description":{"type":"string","title":"Description","description":"Flow description and purpose; empty when none is set"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tag slugs; filter on them with `tags` on `GET /flows/`"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution; `0` when not estimated or never saved"},"visibility":{"$ref":"#/components/schemas/FlowVisibility","description":"Visibility level: `private`, `shared`, or `public`"},"inputs":{"items":{"$ref":"#/components/schemas/FlowInput"},"type":"array","title":"Inputs","description":"All inputs for this flow; check the `required` flag on each to determine which are mandatory. Empty for a flow that was never saved"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when this flow 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":"FlowSummary","description":"Lightweight flow summary for list views."},"FlowVisibility":{"type":"string","enum":["public","private"],"title":"FlowVisibility","description":"Visibility levels for workflows."},"FlowInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use as `id` when providing this input"},"type":{"$ref":"#/components/schemas/NodeType","description":"Input type: `text_input` (text), or `image_input`, `video_input`, `audio_input` or `file_input` (uploaded asset IDs)"},"description":{"type":"string","title":"Description","description":"Generated from the input's label in Studio, as `Input for