{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0","description":"Every public API endpoint, grouped by resource. Paths carry their version."},"servers":[{"url":"/api/public"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"tags":[{"name":"flows","x-page-title":"Flows","x-page-icon":"diagram-project","x-page-description":"Flows represent specific AI-powered capabilities — on-brand photo generation, UGC video generation, static ads generation, and more. Use these endpoints to discover available flows and inspect their required inputs and expected outputs. Flows are always described at their last saved version; autosaved drafts are never exposed here.","description":"Discover flows and inspect their input requirements and output types."},{"name":"agents","x-page-title":"Agents (deprecated)","x-page-icon":"robot","x-page-description":"Agents have been renamed to Flows. These endpoints permanently redirect to their `/flows` equivalents and are removed on 31 December 2026 — see Flows for the current API.","description":"Deprecated. Redirects to /flows; removed 31 December 2026.","x-parent":"flows"},{"name":"runs","x-page-title":"Flow runs","x-page-icon":"circle-play","x-page-description":"Runs are executions of flows. The typical workflow: discover a flow, 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 flow executions."},{"name":"apps","x-page-title":"Apps","x-page-icon":"grid-2","x-page-description":"Apps are curated, runnable applications built on top of flows. Every app, input, setting and output has a `slug`, usable wherever its ID is. Read an app's `input_schema` and `output_schema` (JSON Schema, keyed by slug), start a run with inputs and settings keyed by slug, then poll it and read its `outputs`. Pass `version` to pin a run to one published version of the app.","description":"Discover apps, read their schema, and run them."},{"name":"apps-v1","x-page-title":"Apps v1 (deprecated)","x-page-icon":"grid-2","x-page-description":"Deprecated: use the v2 apps API (`/api/public/v2/apps`), which names every input, setting and output by slug, returns each app's JSON Schema and pins versions. These endpoints keep working unchanged. 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.","x-parent":"apps"},{"name":"app-runs","x-page-title":"App runs v1 (deprecated)","x-page-icon":"circle-play","x-page-description":"Deprecated: v2 runs apps at `POST /api/public/v2/apps/{app}/runs`, with inputs, settings and outputs keyed by slug. These endpoints keep working unchanged. App runs are executions of apps. The workflow mirrors 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.","x-parent":"apps"},{"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 runs (product photos, logos) and outputs produced by them (images, videos). Use these endpoints to upload, retrieve metadata, and download files across the full asset lifecycle — and to organize them with tags, bookmarks, archiving, and deletion.","description":"Upload, retrieve, download, and organize files used as inputs or generated as outputs."}],"paths":{"/v1/flows/":{"get":{"tags":["flows"],"summary":"List Flows","description":"List available flows with filtering options.\n\nThis endpoint returns a paginated list of flows that can generate various types of\ncontent including images, videos, text, and other creative assets.\n\nEach flow is described at its last saved version. A flow that has never been\nsaved — autosave keeps it as a private draft — is still listed, but\nwith an empty `inputs` array and an `estimated_cost` of `0`; it cannot be\nfetched or run until someone saves it. Treat an empty `inputs` as \"not saved\nyet\", not as \"takes no input\".\n\n**Filtering Options:**\n- `tags`: Only flows carrying every given tag slug, case-insensitive (can be\n  provided multiple times; all must match)\n- `visibility`: Only flows with one of these visibilities (can be provided\n  multiple times). Values are lowercase:\n    - `private`: your organization's flows, visible only inside it\n    - `shared`: your organization's flows shared by link\n    - `public`: flows published to everyone, from any organization,\n      including Pletor's catalog\n   By default, only `private` and `shared` flows are returned.\n- `search`: Case- and accent-insensitive substring match on the flow name\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, min: 1, max: 100)\n- `cursor`: `next_cursor` from the previous page (optional)\n\n**Response:**\n- `data`: List of flow summaries with basic information including expected inputs\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results; `null` on the last page\n\n**Error Codes:**\n- `422`: A parameter is out of range or not a valid value (e.g. an unknown\n  `visibility`)\n\n**Use Case:** This is typically the first endpoint called to discover available flows\nbefore getting detailed information or executing them.","operationId":"v1_list_flows_flows__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only flows carrying every given tag slug (case-insensitive); repeat to require several","title":"Tags"},"description":"Only flows carrying every given tag slug (case-insensitive); repeat to require several"},{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FlowVisibility"}},{"type":"null"}],"description":"Only flows with one of these visibilities; repeat to allow several. Defaults to `private` and `shared`","title":"Visibility"},"description":"Only flows with one of these visibilities; repeat to allow several. Defaults to `private` and `shared`"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case- and accent-insensitive substring of the flow name","title":"Search"},"description":"Case- and accent-insensitive substring of the flow 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_FlowSummary_"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/flows/{flow_id}":{"get":{"tags":["flows"],"summary":"Get Flow","description":"Get detailed information about a specific flow.\n\nEverything below describes the flow's **last saved version**, not the draft you\nare editing in the flow builder. Save the flow again to expose newer edits here and to\n`POST /runs`.\n\nThis endpoint retrieves comprehensive information about a flow, including:\n- Flow metadata (name, description, tags)\n- Input requirements with types\n- Output specifications and formats\n- Cost estimate, and whether the flow pauses for human review\n\n**Input Information:**\nEach flow defines specific inputs it requires:\n- `id`: Node identifier used when executing the flow\n- `type`: Input type — `text_input` takes text; `image_input`, `video_input`,\n  `audio_input` and `file_input` take uploaded asset IDs\n- `description`: Generated from the input's label in the flow builder\n- `required`: Whether `POST /runs` rejects a run that omits it\n\nBrand context is not an input: a flow's brand is fixed in the flow and is\nnever listed here or accepted by `POST /runs`.\n\n**Output Information:**\nEach flow specifies what types of content it generates:\n- `id`: Node identifier for the output, matching `id` in run results\n- `type`: Output type (text, images, videos, audio, data)\n- `description`: Generated from the output type\n\n**Cost and Review:**\n- `estimated_cost`: Credit cost estimation for running this flow\n- `has_human_review`: `true` when runs pause for a human review, resolved via\n  `POST /runs/{run_id}/reviews/{review_id}`\n\n**Use Case:** Call this endpoint to understand what inputs a flow needs and what\noutputs it will generate before creating a generation request.\n\n**Error Codes:**\n- `404`: Flow not found or not accessible\n- `422`: Flow has never been saved, so it has no version to describe, or\n  `flow_id` is not a UUID","operationId":"v1_get_flow_flows__flow_id__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Flow 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/Flow"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/agents/":{"get":{"tags":["agents"],"summary":"List agents — use GET /flows/","description":"**Deprecated — send this request to `GET /flows/` instead.** This endpoint permanently redirects (`308`) to `/flows/`, keeping your query string, and is removed on **31 December 2026**. Call `/flows/` directly so your integration stops relying on a redirect. Authenticate as usual: a request without valid credentials answers `401` instead of redirecting.","operationId":"v1_list_agents_agents__get","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"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"}],"responses":{"308":{"description":"Permanent redirect to the `/flows` equivalent, query string preserved.","headers":{"Location":{"description":"The `/flows` URL to send this request to.","schema":{"type":"string","examples":["/api/public/v1/flows/"]}},"Deprecation":{"description":"Always `true` on this endpoint.","schema":{"type":"string","examples":["true"]}},"Sunset":{"description":"The date this endpoint is removed.","schema":{"type":"string","examples":["Thu, 31 Dec 2026 23:59:59 GMT"]}},"Link":{"description":"The successor resource, as `rel=\"successor-version\"`.","schema":{"type":"string","examples":["</api/public/v1/flows/>; rel=\"successor-version\""]}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}},"x-deprecated-sunset":"2026-12-31"}},"/v1/agents/{agent_id}":{"get":{"tags":["agents"],"summary":"Get an agent — use GET /flows/{flow_id}","description":"**Deprecated — send this request to `GET /flows/{flow_id}` instead.** This endpoint permanently redirects (`308`) to `/flows/{flow_id}`, keeping your query string, and is removed on **31 December 2026**. Call `/flows/{flow_id}` directly so your integration stops relying on a redirect. Authenticate as usual: a request without valid credentials answers `401` instead of redirecting.","operationId":"v1_get_agent_agents__agent_id__get","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"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":{"308":{"description":"Permanent redirect to the `/flows` equivalent, query string preserved.","headers":{"Location":{"description":"The `/flows` URL to send this request to.","schema":{"type":"string","examples":["/api/public/v1/flows/3fa85f64-5717-4562-b3fc-2c963f66afa6"]}},"Deprecation":{"description":"Always `true` on this endpoint.","schema":{"type":"string","examples":["true"]}},"Sunset":{"description":"The date this endpoint is removed.","schema":{"type":"string","examples":["Thu, 31 Dec 2026 23:59:59 GMT"]}},"Link":{"description":"The successor resource, as `rel=\"successor-version\"`.","schema":{"type":"string","examples":["</api/public/v1/flows/3fa85f64-5717-4562-b3fc-2c963f66afa6>; rel=\"successor-version\""]}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}},"x-deprecated-sunset":"2026-12-31"}},"/v1/apps/":{"get":{"tags":["apps-v1"],"summary":"List Apps","description":"List available apps with filtering options.\n\nApps are curated, runnable applications built on top of flows. Each app exposes a\nset of configured inputs and produces one or more outputs, and can be executed\ndirectly via `POST /app-runs`.\n\n**What is listed:** the latest version of every active app the caller can see —\ntheir own `private` apps, and `workspace` and `shared` apps from their\norganization, plus every `public` app. A `shared` app from another organization\nis not listed, but can still be fetched by id via `GET /apps/{app_id}`.\n\n**Filtering Options:**\n- `visibility`: Filter apps by their visibility status (can be provided multiple times)\n   Options include:\n    - private: Only visible to the creator\n    - workspace: Visible to everyone in the creator's organization\n    - shared: Visible to anyone holding the app's id or link\n    - public: Visible to everyone\n   By default, all apps accessible to the caller are returned.\n- `search`: Search apps by name or description (case- and accent-insensitive\n  substring match)\n\n**Ordering:** by Pletor's curated position, then by most recent run in the\ncaller's organization (never-run apps by creation date), newest first.\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Response:**\n- `data`: List of app summaries with basic information including expected inputs\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results\n\n**Use Case:** This is typically the first endpoint called to discover available apps\nbefore getting detailed information or executing them.\n\n**Error Codes:**\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `422`: Invalid `visibility` value, or `limit` outside 1–100\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_list_apps_apps__get","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FlowApplicationVisibility"}},{"type":"null"}],"description":"Only return apps with one of these visibility levels (repeat the parameter to pass several)","title":"Visibility"},"description":"Only return apps with one of these visibility levels (repeat the parameter to pass several)"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case- and accent-insensitive substring match on app name or description","title":"Search"},"description":"Case- and accent-insensitive substring match on app 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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/apps/{app_id}":{"get":{"tags":["apps-v1"],"summary":"Get App","description":"Get detailed information about a specific app.\n\nThis endpoint retrieves comprehensive information about an app, including:\n- App metadata (name, description, avatar, visibility)\n- Input requirements with types\n- Output specifications and formats\n- Estimated cost per execution\n\n**Access:** `private` apps are readable only by their creator, `workspace` apps\nby members of the app's organization, and `shared` and `public` apps by any\ncaller. Anything else answers `404`, exactly like an app that does not exist.\n\n**Input Information:**\nEach app defines specific inputs it accepts, in display order:\n- `id`: Node identifier used when executing the app\n- `type`: Input type (text, image, video, audio, file)\n- `name`: Display name of this input\n- `required`: Whether the input is mandatory\n- `options`, `min_selections`, `max_selections`: Constraints for fixed-set inputs.\n  Media `options` are asset IDs owned by the app's organization, so they are\n  `null` for callers outside it.\n\nA brand used by the app's flow is fixed when the flow is built: it is not an\ninput and cannot be set per run.\n\n**Output Information:**\nEach app specifies what types of content it generates:\n- `id`: Node identifier for the output\n- `type`: Output type (text, images, videos, audio, data)\n- `description`: Description of what this output contains\n\nAn output node with no public output type is left out of `outputs`; its\nresults still appear in the run's `results`, with `type` `data`.\n\n**Performance Metrics:**\n- `estimated_cost`: Credit cost estimation for running this app (`0` when no\n  estimate is available)\n\n**Human Review:**\n- `has_human_review`: `true` when a run of this app pauses on a human review\n  step. Resolve each pending review via\n  `POST /app-runs/{run_id}/reviews/{review_id}` within 1 week, or the run fails.\n\n**Use Case:** Call this endpoint to understand what inputs an app needs and what\noutputs it will generate before creating a run.\n\n**Error Codes:**\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `404`: App not found or not accessible\n- `422`: App has no associated flow definition, or `app_id` is not a UUID\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_get_app_apps__app_id__get","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Stable ID of the app","title":"App Id"},"description":"Stable ID of the app"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/assets/":{"get":{"tags":["assets"],"summary":"List Assets","description":"List assets with pagination and optional filtering.\n\nThis endpoint returns a paginated list of assets belonging to your organization,\nnewest first. You can optionally filter by a specific list of asset IDs, by the\nflow or run that produced them, by tag, and by bookmark / archive state.\n\n**What the default listing contains:**\n- Without filters, the list holds the assets generated by your runs. Uploaded\n  files are left out unless you pass `tags`, `bookmarked`, `archived` or\n  `asset_ids`, or look one up by `external_id`.\n- Archived assets are hidden unless you pass `archived` or `asset_ids`.\n- Deleted assets, and assets still being processed (a fresh upload or a\n  just-generated output), are never listed. `external_id` is the exception:\n  it returns the asset in any state.\n\n**Primary Use Cases:**\n- Browse your generated assets with pagination\n- Retrieve specific assets using their IDs\n- Fetch every asset produced by a given flow across all its runs\n- Fetch every asset produced by a specific run\n- Verify the provenance of a known asset list (combine `asset_ids` with\n  `flow_id` or `run_id`)\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Filtering Parameters:**\n- `asset_ids`: Optional list of UUIDs to filter specific assets (repeatable).\n- `flow_id`: Optional flow UUID. Returns all assets produced by that flow\n  across every run.\n- `run_id`: Optional run UUID. Returns all assets produced by that single run.\n- `external_id`: Optional reference id you set at upload. Exact lookup that\n  ignores every other filter.\n- `tags`: Optional tag names (repeatable). Returns assets carrying at least\n  one of them (case-insensitive OR). Unknown tag names match nothing.\n- `bookmarked`: Optional boolean. Filters by bookmark state.\n- `archived`: Optional boolean. `true` shows only archived assets, `false`\n  only non-archived. When omitted, archived assets are hidden (except with\n  `asset_ids`).\n- The filters compose as an AND. For example,\n  `?asset_ids=<id>&flow_id=<flow>` returns the asset only if it was\n  produced by that flow; otherwise the response is empty.\n- `flow_id` and `run_id` only match assets that were produced by a flow\n  run, so uploaded assets are excluded when either filter is set.\n\n**Response:**\nReturns a `CursorPaginatedResponse` object containing:\n- `data`: List of `AssetSummary` objects. Each asset includes `flow_id` and\n  `run_id` so you can correlate it back to the flow / run that produced it.\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page\n\n**Access Control:**\n- Only assets belonging to your organization are returned, except that\n  `asset_ids` also returns `public` / `shared` assets from other\n  organizations\n- Assets not found or not accessible are silently excluded\n\n**Errors:**\n- 401: Missing or invalid API key\n- 422: Invalid parameter (malformed UUID, `limit` outside 1-100)\n- 429: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_list_assets_assets__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"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 (repeat the parameter to pass several). Combines with every other filter as an AND. Unlike the default listing, this lookup also returns uploads, archived assets (unless `archived=false`), and `public`/`shared` assets owned by other organizations.","title":"Asset Ids"},"description":"Restrict the result to this list of asset IDs (repeat the parameter to pass several). Combines with every other filter as an AND. Unlike the default listing, this lookup also returns uploads, archived assets (unless `archived=false`), and `public`/`shared` assets owned by other organizations."},{"name":"flow_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Return only assets produced by this flow (across all its runs). Uploaded assets are never returned by this filter.","title":"Flow Id"},"description":"Return only assets produced by this flow (across all its runs). Uploaded assets are never returned by this filter."},{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Deprecated alias for `flow_id`, removed 31 December 2026. Ignored when `flow_id` is also supplied.","deprecated":true,"title":"Agent Id"},"description":"Deprecated alias for `flow_id`, removed 31 December 2026. Ignored when `flow_id` is also supplied.","deprecated":true},{"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. This is an exact lookup: all other filters are ignored when it is set, and the asset is returned whatever its state — still processing, archived, or deleted.","title":"External Id"},"description":"Return the asset you uploaded with this reference id. Use after a 409 on upload to fetch the existing asset. This is an exact lookup: all other filters are ignored when it is set, and the asset is returned whatever its state — still processing, archived, or deleted."},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Return only assets carrying at least one of these tag names (case-insensitive, OR semantics). Repeat the parameter to pass several: `?tags=summer&tags=hero`. Names that match no tag in your organization match nothing.","title":"Tags"},"description":"Return only assets carrying at least one of these tag names (case-insensitive, OR semantics). Repeat the parameter to pass several: `?tags=summer&tags=hero`. Names that match no tag in your organization match nothing."},{"name":"bookmarked","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"`true` returns only bookmarked assets, `false` only non-bookmarked ones. Omit to ignore the bookmark state.","title":"Bookmarked"},"description":"`true` returns only bookmarked assets, `false` only non-bookmarked ones. Omit to ignore the bookmark state."},{"name":"archived","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"`true` returns only archived assets, `false` only non-archived ones. Omit to hide archived assets (the default), except with `asset_ids`, which returns them unless this is `false`.","title":"Archived"},"description":"`true` returns only archived assets, `false` only non-archived ones. Omit to hide archived assets (the default), except with `asset_ids`, which returns them unless this is `false`."},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/assets/{asset_id}":{"get":{"tags":["assets"],"summary":"Get Asset","description":"Retrieve complete metadata for a specific asset.\n\nThis endpoint returns detailed information about an asset, including its metadata,\naccess URLs, and processing information. Use this when you need complete asset\ndetails rather than just summary information.\n\nUnlike the listing, this returns an asset in any state: one still being\nprocessed, and one that has been deleted (it comes back with\n`archived: true`, and its download answers `410`).\n\n**Parameters:**\n- `asset_id`: UUID of the asset to retrieve\n\n**Response:**\nReturns a complete `Asset` object with all `AssetSummary` fields plus:\n- `asset_metadata`: Dictionary with processing metadata and technical details\n- `is_flow_output_sample`: Whether this asset is a sample from a flow execution\n- `blur_hash`: Hash for progressive image loading (images and videos)\n\n**Access Control:**\n- Asset must be owned by the authenticated user's organization, or\n- Asset must be held open outside it: by a public flow, a demo brain or a\n  Discover inspiration\n\n**Errors:**\n- 401: Missing or invalid API key\n- 404: Asset not found or access denied\n- 422: `asset_id` is not a valid UUID\n- 429: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_get_asset_assets__asset_id__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the asset","title":"Asset Id"},"description":"ID of the asset"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"delete":{"tags":["assets"],"summary":"Delete Asset","description":"Soft-delete an asset.\n\nMarks the asset as deleted (and archived) so it stops appearing in listings\nand can no longer be downloaded or modified: its download, `PATCH` and tag\nendpoints answer `410`. The record is kept, so `GET /assets/{asset_id}` and\n`GET /assets?external_id=` still return it, with `archived: true`. Its\n`external_id` stays claimed. There is no API to restore a deleted asset.\nAn asset still being processed can be deleted.\n\n**Parameters:**\n- `asset_id`: UUID of the asset to delete\n\n**Access Control:**\n- Asset must be owned by the authenticated user's organization. Assets from\n  other organizations are reported as `404` rather than deleted.\n\n**Response:**\n- `204 No Content` on success\n\n**Errors:**\n- 401: Missing or invalid API key\n- 404: Asset not found or access denied\n- 410: Asset has already been deleted\n- 422: `asset_id` is not a valid UUID\n- 429: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_delete_asset_assets__asset_id__delete","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the asset","title":"Asset Id"},"description":"ID of the asset"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"patch":{"tags":["assets"],"summary":"Update Asset","description":"Update an asset's organization flags.\n\nUse this endpoint to bookmark/unbookmark and archive/unarchive an asset.\nFields omitted from the request body, or sent as `null`, are left unchanged;\nan empty body returns the asset as it is.\n\n**Request body:**\n- `bookmarked`: Optional boolean. `true` bookmarks the asset, `false`\n  removes the bookmark.\n- `archived`: Optional boolean. `true` archives the asset (it disappears\n  from default listings; retrieve it with `GET /assets?archived=true`),\n  `false` unarchives it.\n\n**Response:**\nReturns the complete updated `Asset` object.\n\n**Access Control:**\n- Asset must be owned by the authenticated user's organization. Assets from\n  other organizations are reported as `404` rather than updated.\n\n**Errors:**\n- 401: Missing or invalid API key\n- 404: Asset not found or access denied\n- 409: `archived: true` was sent while the asset is still being processed —\n  retry once processing has completed (bookmarking is allowed meanwhile)\n- 410: Asset has been deleted\n- 422: Invalid request body (a field is not a boolean) or malformed `asset_id`\n- 429: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_update_asset_assets__asset_id__patch","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the asset","title":"Asset Id"},"description":"ID of the asset"},{"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/AssetUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/assets/{asset_id}/tags":{"post":{"tags":["assets"],"summary":"Add Asset Tags","description":"Add tags to an asset.\n\nTags are named labels scoped to your organization, shared with the Pletor\nweb app. Adding a tag name that doesn't exist yet creates it automatically;\nnames are matched case-insensitively, and tags already on the asset are\nskipped, so this endpoint is safe to retry. Leading and trailing whitespace\nis trimmed. A name matching an existing tag reuses it with that tag's\noriginal casing: once `Summer` exists, adding `summer` attaches `Summer`.\n\nAn asset that is still being processed (for example a fresh upload) can be\ntagged straight away.\n\n**Request body:**\n- `tags`: Non-empty list of tag names to add (1-50 characters each, after\n  trimming).\n\n**Response:**\nReturns the complete updated `Asset` object; its `tags` field reflects all\ntags now on the asset.\n\n**Retrieval:**\nFilter assets by tag with `GET /assets?tags=<name>` (repeatable, matches\nassets carrying any of the given tags). An asset appears there once its\nprocessing has completed.\n\n**Access Control:**\n- Asset must be owned by the authenticated user's organization.\n\n**Errors:**\n- 401: Missing or invalid API key\n- 404: Asset not found or access denied\n- 410: Asset has been deleted\n- 422: Empty `tags` list, or a tag name that is blank or longer than 50\n  characters\n- 429: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_add_asset_tags_assets__asset_id__tags_post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the asset","title":"Asset Id"},"description":"ID of the asset"},{"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/AssetAddTagsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/assets/{asset_id}/tags/{tag_name}":{"delete":{"tags":["assets"],"summary":"Remove Asset Tag","description":"Remove a tag from an asset.\n\nThe tag is matched by name, case-insensitively. Only the link between the\nasset and the tag is removed — the tag itself remains available in your\norganization. Removing a tag the asset doesn't carry succeeds as a no-op,\nso this endpoint is safe to retry.\n\n**Parameters:**\n- `asset_id`: UUID of the asset\n- `tag_name`: Name of the tag to remove (URL-encode names containing\n  spaces or special characters)\n\n**Response:**\n- `204 No Content` on success\n\n**Access Control:**\n- Asset must be owned by the authenticated user's organization.\n\n**Errors:**\n- 401: Missing or invalid API key\n- 404: Asset not found, access denied, or no tag with this name exists in\n  your organization\n- 410: Asset has been deleted\n- 422: `asset_id` is not a valid UUID\n- 429: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_remove_asset_tag_assets__asset_id__tags__tag_name__delete","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the asset","title":"Asset Id"},"description":"ID of the asset"},{"name":"tag_name","in":"path","required":true,"schema":{"type":"string","description":"Name of the tag to remove, matched case-insensitively. URL-encode names containing spaces or special characters.","title":"Tag Name"},"description":"Name of the tag to remove, matched case-insensitively. URL-encode names containing spaces or special characters."},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/assets/upload/":{"post":{"tags":["assets"],"summary":"Upload Asset","description":"Upload an asset file.\n\nThis endpoint handles the complete asset upload process in a single request:\nsend your file and get back the created asset, with `asset_type: reference`.\n\n**Request (multipart/form-data):**\n- `file`: The file to upload (required, up to 40 MB). Set the part's\n  `Content-Type` to the file's real MIME type — the type is read from that\n  header, not from the file's content. The file's name only picks between\n  extensions that share a MIME type (`.ai` / `.eps`, `.jpg` / `.jpeg`).\n- `visibility`: Accepted for compatibility; uploads are currently always\n  stored as `\"private\"` (only accessible by your organization).\n- `filename`: Optional display filename, used as the downloaded file's name.\n  Defaults to the uploaded file's own name.\n- `external_id`: Optional client-supplied reference id (≤255 chars), unique\n  per organization. Makes the upload safe to retry — reusing a key returns\n  `409` instead of a duplicate asset; fetch the existing one via\n  `GET /assets?external_id=`.\n\n**Supported File Types:**\n- Images: png, jpg/jpeg, webp, gif, svg, heic, heif, avif\n- Video: mp4, mov, webm\n- Audio: mp3, wav\n- Documents and other files: pdf, docx, xlsx, pptx, csv, tsv, txt, json,\n  md, html, css, js, xml, yaml/yml, zip, ai, eps, ttf, otf, woff, woff2\n\n**Response:**\nReturns the created `Asset` object (with `external_id` echoed). Its `id` can\nbe passed to a run straight away — the run waits for processing to finish.\n\n**Processing:**\nThe asset is processed in the background after upload (resizing, previews,\nmetadata extraction). Until processing completes, its `url` / `large_url`\nmay not resolve yet, `GET /assets/{asset_id}/download` answers `425`, the\nasset is left out of `GET /assets` listings (find it with\n`GET /assets/{asset_id}` or `GET /assets?external_id=`), and it cannot be\narchived. It can already be tagged, bookmarked or deleted.\n\n**Errors:**\n- 400: Missing or unsupported file type (see above), or file cannot be read\n- 401: Missing or invalid API key\n- 409: `external_id` already used by another asset (don't retry; GET it instead)\n- 413: File larger than 40 MB. Rejected by the gateway before it reaches the\n  API, so the body is not the usual JSON error envelope.\n- 422: Missing `file` part, or `external_id` longer than 255 characters\n- 429: Rate limit exceeded — retry after the `Retry-After` header\n- 500: Server error during upload or processing\n- 503: Storage service temporarily unavailable","operationId":"v1_upload_asset_assets_upload__post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/assets/{asset_id}/download":{"get":{"tags":["assets"],"summary":"Download Asset","description":"Get a download link for an asset's file.\n\nThe response does not carry the file itself. It is a `text/event-stream`\nbody holding one event, `data: <url>`, where `<url>` is a signed link to the\nfile. Fetch that URL (no API key needed) to get the bytes; it is served as\nan attachment named after the asset's filename and expires after one hour,\nso request a fresh link rather than storing it. Each call marks the asset\nas `downloaded`.\n\n**Primary Use Cases:**\n- Download generated images/videos from completed flow executions\n- Retrieve uploaded assets for local processing or display\n\n**Parameters:**\n- `asset_id`: Asset UUID identifier\n- `svg`: Optional boolean. `true` converts a raster image to SVG and links\n  to the converted file (experimental; SVG sources and non-image assets are\n  returned unchanged)\n- `format`: Optional, for a Create GIF output: `gif` (default) or `mp4`\n\n**Access Control:**\n- Same access rules as `GET /assets/{asset_id}`: owned by your organization,\n  or `public` / `shared`\n\n**Errors:**\n- 401: Missing or invalid API key\n- 404: Asset not found or access denied\n- 410: Asset has been deleted, or its file is no longer available\n- 422: Asset processing failed (re-upload the file), SVG conversion is not\n  available for this asset, or malformed `asset_id`\n- 425: Asset is still being processed — retry in a moment\n- 429: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_download_asset_assets__asset_id__download_get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the asset","title":"Asset Id"},"description":"ID of the asset"},{"name":"svg","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"`true` vectorizes a raster image and returns a URL to the SVG version. Ignored for SVG sources and non-image assets, which are served as they are.","title":"Svg"},"description":"`true` vectorizes a raster image and returns a URL to the SVG version. Ignored for SVG sources and non-image assets, which are served as they are."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"enum":["gif","mp4"],"type":"string"},{"type":"null"}],"description":"For a GIF made by the Create GIF node, which is stored both ways: `gif` (the default) or `mp4`, the same animation as a video. Other assets ignore it.","title":"Format"},"description":"For a GIF made by the Create GIF node, which is stored both ways: `gif` (the default) or `mp4`, the same animation as a video. Other assets ignore it."},{"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":"A `text/event-stream` body holding a single event whose data is a signed download URL, valid for one hour.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"data: https://…/assets/<asset_id>.png?X-Amz-…\n\n"}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/runs/":{"post":{"tags":["runs"],"summary":"Create Run","description":"Create and start a new flow execution run.\n\nThis endpoint launches the execution of a flow with the provided inputs.\nThe execution runs asynchronously, allowing you to monitor progress and retrieve\nresults when complete.\n\nThe run executes the flow's **last saved version**. The flow builder autosaves\nyour edits as a private draft, and drafts never run here — save the flow to put\nyour latest changes behind the API.\n\n**Idempotency with `external_id`:** Optionally pass an `external_id` (e.g. your\nown order or job id). It is **unique per organization**: the first request with\na given key starts the run; any later write reusing that key — including a\ndropped-response retry — is rejected with **`409 conflict`** instead of starting\n(and charging) a duplicate. To fetch the run a key already created, use\n`GET /runs?external_id=...`. The id is echoed on every run response.\n\n- Scope: per organization, across **all** runs (flow and app share the key\n  space) and **all** statuses — a key, once used, stays used.\n- On `409`, do **not** keep retrying the create; `GET /runs?external_id=` to\n  retrieve the existing run (or `GET /app-runs?external_id=` if an app run\n  holds the key). To start a genuinely new run, use a new `external_id`.\n\n**How to Build Inputs:**\n\n1. **First, get flow details**: Call `GET /flows/{flow_id}` to retrieve the flow configuration\n2. **Examine the `inputs` array**: Each object defines what input the flow expects:\n   - `id`: Use this as the `id` in your input object\n   - `type`: Determines the input format (see below)\n   - `description`: Explains what this input does\n   - `required`: Whether the run is rejected without it. An omitted optional\n     input runs with the value saved in the flow.\n\n3. **Format inputs based on type** — `type` is always one of the five below:\n\n**Text Inputs** (`text_input` type) — a string, or a list of strings:\n```json\n{\n    \"id\": \"text_input_node_id\",\n    \"value\": \"Your text content here\"\n}\n```\n\n**Asset Inputs** (`image_input`, `video_input`, `audio_input`, `file_input` types):\n```json\n{\n    \"id\": \"image_input_node_id\",\n    \"value\": {\n        \"asset_ids\": [\"uuid1\", \"uuid2\"]\n    }\n}\n```\nNote: Upload assets first via `POST /assets/upload` to get the UUIDs. A bare\nlist of asset UUIDs is accepted as `value` too.\n\nNothing else in a flow can be set per run: brand (Brain) content and fonts\nare part of the saved flow, never listed in `inputs`.\n\n**Complete Example Workflow:**\n\n1. Get flow configuration:\n```bash\nGET /flows/550e8400-e29b-41d4-a716-446655440000\n# Response shows inputs: [\n#   {\"id\": \"uuid-1\", \"type\": \"text_input\", \"description\": \"Product description\"},\n#   {\"id\": \"uuid-2\", \"type\": \"image_input\", \"description\": \"Company logo\"}\n# ]\n```\n\n2. Upload assets if needed:\n```bash\nPOST /assets/upload\n# Response: {\"id\": \"asset-uuid-123\", ...}\n```\n\n3. Create run with matching inputs:\n```json\n{\n    \"flow_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"inputs\": [\n        {\n            \"id\": \"uuid-1\",\n            \"value\": \"Create a marketing banner for a tech startup\"\n        },\n        {\n            \"id\": \"uuid-2\",\n            \"value\": {\n                \"asset_ids\": [\"asset-uuid-123\"]\n            }\n        }\n    ]\n}\n```\n\n**Response:**\n- `201` with the Run object: `status` is `in_progress`, and `inputs` echoes\n  the request\n- Use `id` field to monitor progress via `GET /runs/{run_id}`\n- Credits are checked once execution starts: a run the organization cannot\n  afford ends `failed` with `failure_reason` `insufficient_credits`, not as an\n  error on this call\n\n**Running an app instead?** Apps have their own surface — use `POST /app-runs`\nwith an `app_id`. App runs pause on human review too, and are resolved via\n`POST /app-runs/{run_id}/reviews/{review_id}`. See the Apps and App Runs\nsections.\n\n**Error Codes:**\n- `400`: An input `id` the flow doesn't have, a missing required input, an\n  asset input without `asset_ids`, a flow with configuration errors, or a\n  flow that has never been saved and so has no version to run\n- `401`: Missing or invalid API key / Bearer token\n- `403`: `X-Organization-Id` names an organization you can't act in\n- `404`: Flow not found or not accessible\n- `409`: `external_id` is already used by a run in this organization\n- `422`: Malformed body (e.g. `flow_id` not a UUID, `external_id` over 255\n  characters), or input values the flow's nodes would reject before running\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_create_run_runs__post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"get":{"tags":["runs"],"summary":"List Runs","description":"List flow execution runs with filtering options.\n\nThis endpoint returns a paginated list of the organization's flow execution\nruns, newest first, with their current status and basic metadata. App runs\nare listed separately via `GET /app-runs`.\n\n**Filtering Options:**\n- `status`: Filter by execution status (in_progress, completed, failed, canceled).\n  Runs paused on a human review are `in_progress`.\n- `external_id`: Filter to runs you tagged with this reference id at creation.\n  Use this to check whether you already started a run for a given item before\n  starting another. A key held by an app run is found via `GET /app-runs`.\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, min: 1, max: 100)\n- `cursor`: Pass the previous page's `next_cursor` unchanged to get the next page\n\n**Response:**\n- `data`: List of run summaries with basic information (no inputs, results,\n  or pending reviews — fetch `GET /runs/{run_id}` for those)\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results; null on the last page\n\n**Use Case:** Monitor multiple executions and their status overview.\n\n**Error Codes:**\n- `401` / `403` / `429`: Authentication, organization access, or rate limit\n- `422`: Invalid `status` value, or `limit` outside 1–100","operationId":"v1_list_runs_runs__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FlowRunStatus"},{"type":"null"}],"description":"Only return runs in this status","title":"Status"},"description":"Only return runs in this status"},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only return the run created with this `external_id` (exact match; at most one run, since keys are unique per organization)","title":"External Id"},"description":"Only return the run created with this `external_id` (exact match; at most one run, since keys are unique per organization)"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/runs/{run_id}":{"get":{"tags":["runs"],"summary":"Get Run","description":"Get detailed information about a specific flow execution run.\n\nThis endpoint retrieves comprehensive information about an execution run,\nincluding real-time status, progress, inputs, and results when available.\n\n**Monitoring Workflow:**\n1. Create run via `POST /runs`\n2. Poll this endpoint to monitor progress\n3. If `awaiting_human_review` becomes `true`, inspect `pending_reviews`\n   and resolve each via `POST /runs/{run_id}/reviews/{review_id}` to\n   resume execution. A review left undecided for a week cancels the run\n   (`failure_reason: timeout`).\n4. Stop polling when status becomes \"completed\", \"failed\", or \"canceled\"\n5. Extract results from the `results` array when status is \"completed\"\n\n**Status Lifecycle:**\n- `in_progress`: Executing, or paused on a human review\n- `completed`: Every node finished\n- `failed`: A node failed, or credits ran out. Nodes that finished first\n  keep their `results`, so they can be partial\n- `canceled`: Stopped via `DELETE /runs/{run_id}`\n\n**Progress Tracking:**\n- `status`: Current execution state\n- `progress`: Rough completion indicator (0.0 to 1.0)\n- `current_node`: Type of a node currently executing (`human_review` while\n  paused on a review); null once the run has ended\n- `awaiting_human_review`: `true` when the run is paused on a human\n  review node; `status` stays `in_progress` in this case\n- `pending_reviews`: List of review steps awaiting a decision\n- `created_at` / `started_at`: When the run was created / started executing\n- `completed_at`: When the run ended (if applicable)\n\n**How to Retrieve Results:**\n\nWhen the run status becomes \"completed\", the `results` array contains the flow outputs.\nCall `GET /flows/{flow_id}` and examine the `outputs` array to understand what\nresults to expect, then match results to outputs by `id`. `results` also\ncarries intermediate nodes' outputs — ignore the ids you don't need.\n\n**Text Results** (`type` `text`): `value` is a string, or a list of strings.\n\n**Asset Results** (`images`, `videos`, `audio`): `value` is an array of asset UUIDs.\nResolve each via `GET /assets/{id}` and fetch the `url` field.\n\n**Data Results** (`data`): `value` is the node's raw output object.\n\n**Cost Information:**\n- `cost`: Credits consumed so far; final once the run has ended\n\n**Error Handling:**\n- `error`: Error message if the run failed or was canceled\n- `failure_reason`: Categorized cause, set when the run failed or was canceled\n\n**Error Codes:**\n- `401` / `403` / `429`: Authentication, organization access, or rate limit\n- `404`: Run not found or not accessible — including app runs, which are read\n  via `GET /app-runs/{run_id}`\n- `422`: `run_id` is not a UUID","operationId":"v1_get_run_runs__run_id__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`.","title":"Run Id"},"description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"delete":{"tags":["runs"],"summary":"Cancel Run","description":"Cancel an ongoing flow execution run.\n\nThis endpoint stops a run whose `status` is `in_progress` — including one\npaused on a human review. Once cancelled, the execution cannot be resumed.\n\n**Behavior:**\n- Only `in_progress` runs can be cancelled\n- `204` means cancellation was requested; `status` becomes `canceled` a few\n  seconds later, with `failure_reason` `canceled`\n- Nodes that already finished keep their `results`, and credits they\n  consumed stay in `cost`\n- Pending reviews can no longer be submitted (`409`)\n- App runs are cancelled via `DELETE /app-runs/{run_id}`\n\n**Error Codes:**\n- `401` / `403` / `429`: Authentication, organization access, or rate limit\n- `404`: Run not found or not accessible, an app run, or a run that is no\n  longer `in_progress` (completed, failed, or already canceled) — so a\n  repeated cancel returns `404`\n- `422`: `run_id` is not a UUID","operationId":"v1_cancel_run_runs__run_id__delete","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`.","title":"Run Id"},"description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/runs/{run_id}/reviews/{review_id}":{"post":{"tags":["runs"],"summary":"Submit Review","description":"Resolve a pending human review and resume an execution.\n\nWhen a flow includes a human review step, the run pauses on that node\nand `awaiting_human_review` becomes `true` on `GET /runs/{run_id}` (and\n`has_human_review` is `true` on the flow). Each waiting step is listed in\nthe run's `pending_reviews` array, and `status` stays `in_progress`.\nSubmit a decision here to resume. A review left undecided for one week\nfails the run.\n\nThis endpoint serves flow runs only. App runs pause the same way; resolve\ntheirs via `POST /app-runs/{run_id}/reviews/{review_id}`.\n\n**Discovering pending reviews**\n\n1. Poll `GET /runs/{run_id}` until `awaiting_human_review` is `true`.\n2. Inspect the `pending_reviews` array. Use a review's `id` as\n   `review_id` in this endpoint's path.\n3. The `proposed_output` field of each review is what the upstream node\n   generated. Submit it back as `output` (optionally edited) to approve.\n\n**Decisions**\n\n- `approve`: continue execution. The `output` body field is required and\n  must match the shape of `proposed_output`:\n  - Image / video / audio reviews: `{\"asset_ids\": [\"...\"]}`.\n  - Text reviews: `{\"prompts\": [\"...\"]}` (the reviewed node's own text key,\n    as seen in `proposed_output`, is accepted too).\n  To discard items, approve with only the ones you want to keep — omitted\n  items are dropped. At least one item must be kept (an empty `output` is\n  rejected with `400`).\n- `retry`: re-run the upstream node(s) to produce a new candidate output.\n  `output` is ignored. The review keeps its `id` and stays in\n  `pending_reviews`; its `proposed_output` is null while the upstream\n  node regenerates, then shows the new candidate — decide again once it\n  does. `can_generate_more` tells you whether the flow offers this; the\n  API accepts `retry` regardless.\n\nA `204` means the decision was delivered; poll `GET /runs/{run_id}` to\nfollow the run from there.\n\n**Examples**\n\nApprove an image review using the proposed assets:\n```json\n{\n    \"decision\": \"approve\",\n    \"output\": {\n        \"asset_ids\": [\n            \"asset-uuid-001\",\n            \"asset-uuid-002\"\n        ]\n    }\n}\n```\n\nDiscard some of the proposed assets by approving with only the kept subset:\n```json\n{\"decision\": \"approve\", \"output\": {\"asset_ids\": [\"asset-uuid-001\"]}}\n```\n\nRetry to regenerate the upstream output:\n```json\n{\"decision\": \"retry\"}\n```\n\n**Error Codes:**\n- `400`: Missing `output`, an empty `output` (nothing kept), or an `output`\n  whose shape doesn't match the review, when decision is `approve`.\n- `401` / `403` / `429`: Authentication, organization access, or rate limit.\n- `404`: Run not found (app runs included — see above), or no human review\n  with that ID on this run.\n- `409`: The review is no longer waiting (already submitted, or the run\n  finished/failed/was canceled). Checked before the review ID, so any\n  `review_id` on an ended run returns `409`.\n- `422`: Malformed body (e.g. a `decision` other than `approve`/`retry`),\n  or a path ID that is not a UUID.","operationId":"v1_submit_review_runs__run_id__reviews__review_id__post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`.","title":"Run Id"},"description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`."},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"`id` of an entry in the run's `pending_reviews`","title":"Review Id"},"description":"`id` of an entry in the run's `pending_reviews`"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/app-runs/":{"post":{"tags":["app-runs"],"summary":"Create App Run","description":"Create and start a new app execution run.\n\nThis endpoint launches the execution of an app with the provided inputs. The\nexecution runs asynchronously, allowing you to monitor progress and retrieve\nresults when complete. The run executes the flow version pinned by the app's\nlatest version and starts with `status` `in_progress`.\n\n**Idempotency with `external_id`:** Optionally pass an `external_id` (e.g. your\nown order or job id). It is **unique per organization**: the first request with\na given key starts the run; any later write reusing that key — including a\ndropped-response retry — is rejected with **`409 conflict`** instead of starting\n(and charging) a duplicate. To fetch the run a key already created, use\n`GET /app-runs?external_id=...`. The id is echoed on every app-run response.\n\n- Scope: per organization, across **all** runs (flow and app share the key\n  space) and **all** statuses — a key, once used, stays used.\n- On `409`, do **not** keep retrying the create; `GET /app-runs?external_id=` to\n  retrieve the existing run. To start a genuinely new run, use a new `external_id`.\n\n**How to Build Inputs:**\n\n1. **First, get app details**: Call `GET /apps/{app_id}` to retrieve the app\n   configuration.\n2. **Examine the `inputs` array**: Each object defines what input the app expects:\n   - `id`: Use this as the `id` in your input object\n   - `type`: text, image, video, audio, or file\n   - `required`: whether the input is mandatory\n   - `options` / `min_selections` / `max_selections`: constraints for fixed-set inputs\n\n**Text Inputs:** a string, or a list of strings (each string counts as one\nselection against `min_selections` / `max_selections`; with `options`, each\nmust be one of the listed labels).\n```json\n{\"id\": \"text_input_node_id\", \"value\": \"Your text content here\"}\n```\n\n**Asset Inputs** (image / video / audio / file): an object with `asset_ids`\n(a bare list of asset IDs is also accepted). With `options`, each ID must be\none of the listed asset IDs.\n```json\n{\"id\": \"image_input_node_id\", \"value\": {\"asset_ids\": [\"uuid1\", \"uuid2\"]}}\n```\nUpload assets first via `POST /assets/upload` to get the UUIDs.\n\nA brand used by the app's flow is not an input: it is fixed on the flow and\ncannot be passed per run.\n\n**Example:**\n```json\n{\n    \"app_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"inputs\": [\n        {\"id\": \"uuid-1\", \"value\": \"Create a marketing banner for a tech startup\"}\n    ]\n}\n```\n\n**Curated contract:** only the inputs advertised by `GET /apps/{app_id}` are\naccepted. Unknown input ids, missing required inputs, and values that violate an\ninput's `options` / `min_selections` / `max_selections` are rejected with `400`.\nThe run's `results` contain only the app's curated outputs — never the\nunderlying flow's internal nodes.\n\n**Credits:** the balance is not checked when the run is created. A run that\nexhausts the organization's credits or the user's quota fails with\n`failure_reason` `insufficient_credits`.\n\n**Response:**\n- AppRun object with execution details and initial status\n- Use `id` to monitor progress via `GET /app-runs/{run_id}`\n\n**Error Codes:**\n- `400`: Invalid input format, unknown input id, missing required inputs, values\n  outside constraints, or an app whose flow has validation errors or no flow\n  definition\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `404`: App not found or not accessible\n- `409`: `external_id` already used by another run in this organization\n- `422`: Malformed request body (e.g. `external_id` over 255 characters), or\n  inputs that a node of the flow would reject before running\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_create_app_run_app_runs__post","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"get":{"tags":["app-runs"],"summary":"List App Runs","description":"List app execution runs with filtering options.\n\nThis endpoint returns a paginated list of app execution runs with their current\nstatus and basic metadata, newest first. It covers every app run in the caller's\norganization, whoever started it. Flow runs are listed separately via\n`GET /runs`.\n\n**Filtering Options:**\n- `status`: Filter by execution status (in_progress, completed, failed, canceled)\n- `external_id`: Filter to runs you tagged with this reference id at creation.\n  Use this to check whether you already started a run for a given item before\n  starting another.\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Response:**\n- `data`: List of app-run summaries with basic information. Summaries carry no\n  `inputs`, `results` or `pending_reviews` — fetch `GET /app-runs/{run_id}`\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results\n\n**Error Codes:**\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `422`: Invalid `status` value, or `limit` outside 1–100\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_list_app_runs_app_runs__get","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FlowRunStatus"},{"type":"null"}],"description":"Only return runs in this status","title":"Status"},"description":"Only return runs in this status"},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only return the run created with this external_id","title":"External Id"},"description":"Only return the run created with this 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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/app-runs/{run_id}":{"get":{"tags":["app-runs"],"summary":"Get App Run","description":"Get detailed information about a specific app execution run.\n\nThis endpoint retrieves comprehensive information about an app run, including\nreal-time status, progress, inputs, and curated results when available.\n\n**Monitoring Workflow:**\n1. Create run via `POST /app-runs`\n2. Poll this endpoint to monitor progress\n3. If `awaiting_human_review` becomes `true`, inspect `pending_reviews`\n   and resolve each via `POST /app-runs/{run_id}/reviews/{review_id}` to\n   resume execution (within 1 week, or the run fails)\n4. Stop polling when status becomes \"completed\", \"failed\", or \"canceled\"\n5. Extract results from the `results` array when status is \"completed\"\n\n**Progress Tracking:**\n- `status`: `in_progress` until the run ends as `completed`, `failed` or\n  `canceled`\n- `progress`: Fraction of node executions completed (0.0 to 1.0)\n- `current_node`: Type of the node executing now, while `in_progress`\n- `awaiting_human_review`: `true` when the run is paused on a human review\n  node; `status` stays `in_progress` in this case\n- `pending_reviews`: List of review steps awaiting a decision\n\n**How to Retrieve Results:**\nCall `GET /apps/{app_id}` and examine the `outputs` array, then match results to\noutputs by `id`. Results appear as each output node finishes, so `results` can\nbe partial while the run is `in_progress` or after it fails.\n\n- **Text results**: `value` is a string, or a list of strings.\n- **Asset results** (images/videos/audio): `value` is an array of asset UUIDs —\n  resolve each via `GET /assets/{id}` and fetch the `url` field.\n- **Data results**: `value` is the node's raw output object.\n\n**Cost Information:**\n- `cost`: Credits consumed so far (`null` before any node has run)\n\n**Error Handling:**\n- `error`: Error message if the run failed or was canceled\n- `failure_reason`: Categorized cause, set when `status` is `failed` or\n  `canceled`\n\n**Error Codes:**\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `404`: Run not found in the caller's organization, or it is a flow run\n  (use `GET /runs/{run_id}`)\n- `422`: `run_id` is not a UUID\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_get_app_run_app_runs__run_id__get","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the app run","title":"Run Id"},"description":"ID of the app run"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"delete":{"tags":["app-runs"],"summary":"Cancel App Run","description":"Cancel an ongoing app execution run.\n\nThis endpoint allows you to cancel an execution whose `status` is\n`in_progress`, including one paused on a human review. Once cancelled, the\nexecution cannot be resumed.\n\n**Behavior:**\n- The `204` confirms the cancellation was requested; it takes effect\n  asynchronously, usually within a few seconds\n- Once it lands, `GET /app-runs/{run_id}` shows `status` `canceled` and\n  `failure_reason` `canceled`\n- A run that is already `completed`, `failed` or `canceled` cannot be\n  cancelled and answers `404`\n\n**Error Codes:**\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `404`: Run not found in the caller's organization, it is a flow run, or it\n  is no longer `in_progress`\n- `422`: `run_id` is not a UUID\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_cancel_app_run_app_runs__run_id__delete","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the app run","title":"Run Id"},"description":"ID of the app run"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/app-runs/{run_id}/reviews/{review_id}":{"post":{"tags":["app-runs"],"summary":"Submit App Run Review","description":"Resolve a pending human review and resume an app execution.\n\nWhen the app's underlying flow includes a human review step, the run pauses\non that node and `awaiting_human_review` becomes `true` on\n`GET /app-runs/{run_id}`. Each waiting step is listed in the run's\n`pending_reviews` array. Submit a decision here to resume. A review left\nwithout a decision for 1 week cancels the run (`failure_reason: timeout`).\n\nApp runs are resolved only here: `POST /runs/{run_id}/reviews/{review_id}`\nanswers `404` for an app run.\n\n**Discovering pending reviews**\n\n1. Poll `GET /app-runs/{run_id}` until `awaiting_human_review` is `true`.\n2. Inspect the `pending_reviews` array. Use a review's `id` as\n   `review_id` in this endpoint's path.\n3. The `proposed_output` field of each review is what the upstream node\n   generated. Submit it back as `output` (optionally edited) to approve.\n\n**Decisions**\n\n- `approve`: continue execution. The `output` body field is required and\n  must match the shape of `proposed_output`:\n  - Image / video / audio reviews: `{\"asset_ids\": [\"...\"]}`.\n  - Text-prompt reviews: `{\"prompts\": [\"...\"]}`.\n  To discard items, approve with only the ones you want to keep — omitted\n  items are dropped. At least one item must be kept (an empty `output` is\n  rejected with `400`), and an `output` whose shape does not match the\n  reviewed node is rejected with `400`.\n- `retry`: re-run the upstream node(s) to produce a new candidate output.\n  `output` is ignored. The same review (same `id`) stays in\n  `pending_reviews` and `awaiting_human_review` stays `true` while the\n  upstream regenerates; its `proposed_output` is refreshed when that\n  finishes. Wait for the new `proposed_output` before deciding again — a\n  decision sent earlier is applied as soon as regeneration ends.\n\n**Examples**\n\nApprove an image review using the proposed assets:\n```json\n{\n    \"decision\": \"approve\",\n    \"output\": {\n        \"asset_ids\": [\n            \"asset-uuid-001\",\n            \"asset-uuid-002\"\n        ]\n    }\n}\n```\n\nRetry to regenerate the upstream output:\n```json\n{\"decision\": \"retry\"}\n```\n\n**Error Codes:**\n- `400`: Missing `output`, an empty `output` (nothing kept), or an `output`\n  that does not match the reviewed node's shape, when decision is `approve`.\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `404`: Run not found in the caller's organization, it is a flow run, the\n  caller can no longer read the app, or no human review with that ID on\n  this run.\n- `409`: The review is no longer waiting (already submitted, or the run\n  finished/failed/was canceled).\n- `422`: Malformed body (e.g. `decision` not `approve` or `retry`) or a\n  path ID that is not a UUID\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_submit_app_run_review_app_runs__run_id__reviews__review_id__post","deprecated":true,"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the app run","title":"Run Id"},"description":"ID of the app run"},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"`id` of an entry in the run's `pending_reviews`","title":"Review Id"},"description":"`id` of an entry in the run's `pending_reviews`"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v2/apps/":{"get":{"tags":["apps"],"summary":"List Apps","description":"List the apps you can run: your own, your organization's, and public ones.\n\nEach app carries its `slug`, usable in place of its `id` in every path, and\nits latest `version`. Ordered by Pletor's curated position, then by most\nrecent run in your organization.\n\n**Error Codes:**\n- `422`: Invalid `visibility` value, or `limit` outside 1–100\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v2_list_apps_apps__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FlowApplicationVisibility"}},{"type":"null"}],"description":"Only apps with one of these visibilities (repeatable)","title":"Visibility"},"description":"Only apps with one of these visibilities (repeatable)"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case- and accent-insensitive match on name or description","title":"Search"},"description":"Case- and accent-insensitive match on 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_AppV2Summary_"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v2/apps/{app}":{"get":{"tags":["apps"],"summary":"Get App","description":"Get an app and the JSON Schemas of what a run takes and returns.\n\n`input_schema` describes a run's `inputs`, `settings` and, when some outputs\nare optional, `outputs` — every field keyed by its slug, with its display\nname as `title`, its allowed values as `enum`, how many items it takes as\n`minItems` / `maxItems`, and a setting's `default`. `output_schema` describes\nthe `outputs` of a finished run. Use them as is to validate a request,\ngenerate a client, or build a form.\n\n`versions` lists every published version, newest first. `breaking` marks a\nversion a caller of the previous one has to adapt to; pin `version` on runs\nto keep calling an older one.\n\n**Error Codes:**\n- `404`: App or version not found or not accessible\n- `422`: `version` is not a positive integer\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v2_get_app_apps__app__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"app","in":"path","required":true,"schema":{"type":"string","description":"The app's ID, or its `slug` (an app of your own organization)","title":"App"},"description":"The app's ID, or its `slug` (an app of your own organization)"},{"name":"version","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Describe this version instead of the latest","title":"Version"},"description":"Describe this version instead of the latest"},{"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/AppV2"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v2/apps/{app}/runs":{"post":{"tags":["apps"],"summary":"Create Run","description":"Start a run of the app.\n\nPass `inputs`, `settings` and `outputs` keyed by slug, as the app's\n`input_schema` describes. Without `version`, the run executes the version\nthat is latest when it starts; with it, exactly that version, even after the\napp is republished.\n\n**Idempotency:** an `external_id` is unique per organization. Reusing one\nanswers `409` instead of starting (and charging) a second run; fetch the\nfirst with `GET /apps/{app}/runs?external_id=...`.\n\n**Credits:** the balance is not checked here. A run that exhausts it fails\nwith `failure_reason` `insufficient_credits`.\n\n**Error Codes:**\n- `400`: Unknown slug, missing required input, or a value the schema rejects\n- `404`: App or version not found or not accessible\n- `409`: `external_id` already used in this organization\n- `422`: Malformed body\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v2_create_run_apps__app__runs_post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"app","in":"path","required":true,"schema":{"type":"string","description":"The app's ID, or its `slug` (an app of your own organization)","title":"App"},"description":"The app's ID, or its `slug` (an app of your own organization)"},{"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/AppV2RunCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppV2Run"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"get":{"tags":["apps"],"summary":"List Runs","description":"List the app's runs in your organization, newest first.\n\nSummaries carry no inputs, outputs or reviews: fetch a run for those.\n\n**Error Codes:**\n- `404`: App or version not found or not accessible\n- `422`: Invalid `status`, `version` or `limit`\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v2_list_runs_apps__app__runs_get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"app","in":"path","required":true,"schema":{"type":"string","description":"The app's ID, or its `slug` (an app of your own organization)","title":"App"},"description":"The app's ID, or its `slug` (an app of your own organization)"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FlowRunStatus"},{"type":"null"}],"description":"Only runs in this status","title":"Status"},"description":"Only runs in this status"},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the run created with this external_id","title":"External Id"},"description":"Only the run created with this external_id"},{"name":"version","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Only runs of this app version","title":"Version"},"description":"Only runs of this app version"},{"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_AppV2RunSummary_"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v2/apps/{app}/runs/{run_id}":{"get":{"tags":["apps"],"summary":"Get Run","description":"Get a run, with its `outputs` keyed by slug.\n\nPoll until `status` leaves `in_progress`. Outputs appear as they are\nproduced, so they can be partial while running or after a failure. Media\noutputs are asset IDs: `GET /v1/assets/{id}` resolves them. While\n`awaiting_human_review` is true the run is paused: resolve each of its\n`pending_reviews` within a week, or the run fails.\n\n**Error Codes:**\n- `404`: App not accessible, or no run of this app with that ID\n- `422`: `run_id` is not a UUID\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v2_get_run_apps__app__runs__run_id__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"app","in":"path","required":true,"schema":{"type":"string","description":"The app's ID, or its `slug` (an app of your own organization)","title":"App"},"description":"The app's ID, or its `slug` (an app of your own organization)"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the run","title":"Run Id"},"description":"ID of the run"},{"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/AppV2Run"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v2/apps/{app}/runs/{run_id}/cancel":{"post":{"tags":["apps"],"summary":"Cancel Run","description":"Cancel a run that is `in_progress`, including one paused on a review.\n\nCancellation lands within a few seconds; the run then reads `canceled`, and\nstays readable.\n\n**Error Codes:**\n- `404`: App not accessible, no run of this app with that ID, or the run is\n  no longer `in_progress`\n- `422`: `run_id` is not a UUID\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v2_cancel_run_apps__app__runs__run_id__cancel_post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"app","in":"path","required":true,"schema":{"type":"string","description":"The app's ID, or its `slug` (an app of your own organization)","title":"App"},"description":"The app's ID, or its `slug` (an app of your own organization)"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the run","title":"Run Id"},"description":"ID of the run"},{"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/AppV2Run"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v2/apps/{app}/runs/{run_id}/reviews/{review_id}":{"post":{"tags":["apps"],"summary":"Submit Review","description":"Resolve a pending human review and resume the run.\n\n- `approve` continues with `output`, in the shape of the review's\n  `proposed_output`. Keep only the items you want; at least one.\n- `retry` regenerates the reviewed step. The same review stays pending and\n  its `proposed_output` refreshes when the new one is ready.\n\n**Error Codes:**\n- `400`: Missing, empty or mismatched `output` on `approve`\n- `404`: App not accessible, no run of this app with that ID, or no such review\n- `409`: The review is no longer waiting\n- `422`: Malformed body or path ID\n- `401`: Missing or invalid API key or Bearer token\n- `403`: The API key is bound to a different organization than `X-Organization-Id`\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v2_submit_review_apps__app__runs__run_id__reviews__review_id__post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"app","in":"path","required":true,"schema":{"type":"string","description":"The app's ID, or its `slug` (an app of your own organization)","title":"App"},"description":"The app's ID, or its `slug` (an app of your own organization)"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of the run","title":"Run Id"},"description":"ID of the run"},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"`id` of an entry in the run's `pending_reviews`","title":"Review Id"},"description":"`id` of an entry in the run's `pending_reviews`"},{"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 (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}},"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.","example":{"avatar_url":"https://cdn.example.com/apps/banner.png","description":"Generate marketing banners from a text prompt and logo","estimated_cost":50,"has_human_review":false,"id":"550e8400-e29b-41d4-a716-446655440000","inputs":[{"id":"uuid-1","name":"Product description","required":true,"type":"text"},{"id":"uuid-2","name":"Company logo","required":false,"type":"image"}],"name":"Marketing Banner App","outputs":[{"description":"Generated banner","id":"uuid-3","type":"images"}],"visibility":"public"}},"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."},"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.0,"minimum":0.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.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 cancels the run (`failure_reason: timeout`).","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.","example":{"app_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"}},"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.","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: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1.0,"minimum":0.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.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."},"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."},"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."},"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."},"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","created_at","updated_at","url","agent_id"],"title":"Asset","description":"Complete asset with all metadata."},"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."},"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."},"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","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."},"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."},"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"},"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_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]"},"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":"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."},"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)."},"Flow":{"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/`"},"inputs":{"items":{"$ref":"#/components/schemas/FlowInput"},"type":"array","title":"Inputs","description":"All inputs for this flow. Use these IDs when creating a run; check the `required` flag on each input to determine which are mandatory"},"outputs":{"items":{"$ref":"#/components/schemas/FlowOutput"},"type":"array","title":"Outputs","description":"Expected outputs. Match these IDs in run results, which can also hold other nodes. Output nodes with no public data type are not listed"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution; `0` when not estimated"},"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"],"title":"Flow","description":"Complete representation of a flow 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":"Input for Product description","id":"uuid-1","required":true,"type":"text_input"},{"description":"Input for Company logo","id":"uuid-2","required":false,"type":"image_input"}],"name":"Marketing Banner Generator","outputs":[{"description":"Generated images","id":"uuid-3","type":"images"}],"tags":["marketing","image"]}},"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"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 the flow builder, as `Input for <label>`"},"required":{"type":"boolean","title":"Required","description":"Whether this input must be provided when creating a run; a missing required input answers `400 invalid_input`","default":true}},"type":"object","required":["id","type","description"],"title":"FlowInput","description":"An input a caller supplies when running a flow. Only user-input nodes are\nlisted; brand context is fixed in the flow and is never an input."},"FlowOutput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to match against `id` in run results"},"type":{"$ref":"#/components/schemas/DataType","description":"Output data type: text, images, videos, audio, or data"},"description":{"type":"string","title":"Description","description":"Generated from the data type, as `Generated <type>`"}},"type":"object","required":["id","type","description"],"title":"FlowOutput","description":"An output produced by a flow."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"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."},"MediaExtension":{"type":"string","enum":["png","jpg","jpeg","svg","heic","heif","avif","webp","gif","mp4","wav","mp3","mov","webm","pdf","docx","xlsx","pptx","csv","tsv","txt","json","md","html","css","js","xml","yaml","yml","zip","ai","eps","ttf","otf","woff","woff2","glb"],"title":"MediaExtension"},"MediaType":{"type":"string","enum":["image","video","audio","file","design","animated_design","scene","model_3d"],"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","input_font","input_design","input_animated_design","input_product","input_character","input_brain","input_whole_brain","input_colors","llm","image_generation","video_generation","text_to_speech","screen_mockup","remove_background","upscale","upscale_video","video_background_removal","extract_video_frame","create_gif","extend_video","reframe_video","image_generation_lora","change_aspect_ratio","crop_expand_image","color_grade_image","split_image_layers","merge_image_layers","meta_ads_extractor","image_edit","edit_text","relight_image","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","find_in_brain","googledrive_upload_file","import_google_sheet","import_airtable","prompt_concatenate","text_split","list_selector","video_edit","router","camera_angle","rename_asset","music_generation","generate_audio","merge_audio_video","trim_speed","extract_audio","remove_audio","isolate_sound","change_voice","translate_audio","translate_video","transcribe","run_task","run_agent","auto_compose_design","generate_3d_model"],"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} — 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.","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.\n\n`approve` resumes the run with the submitted output; `retry` re-runs the\nreviewed upstream node(s) and waits for a new decision on the same review."},"Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"flow_id":{"type":"string","format":"uuid","title":"Flow Id","description":"ID of the flow 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` until the run ends, then `completed`, `failed`, or `canceled`. Stays `in_progress` while paused on a human review."},"progress":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Progress","description":"Rough completion indicator from 0.0 to 1.0: the share of the nodes started so far that have finished, so it can move backwards as new nodes start. 1.0 when completed; 0.0 when failed or canceled.","default":0.0},"current_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"Type of a node currently executing (e.g. image_generation, llm, or human_review while paused on a review). Null unless 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 the run ended (completed, failed, or canceled). Null while in_progress."},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs for this run. The create response echoes the request as sent; later reads return the stored values (text as a list of strings, assets as {\"asset_ids\": [...]})."},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"One entry per executed node that produced output — intermediate nodes included, not only the flow's `outputs`; match by `id`. Entries appear as nodes finish, so an in-progress or failed run can carry partial results. After a review `retry`, each node reports its latest output."},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed so far, summed over the run's nodes. Grows while the run is in progress; null before any node has started."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message when the run failed or was canceled. Null otherwise."},"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 (`canceled` for a user cancellation); null otherwise."},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","flow_id","status","created_at","agent_id"],"title":"Run","description":"Complete representation of a flow execution run.\n\n`status` starts at `in_progress` and ends at `completed`, `failed` or\n`canceled`. A run paused on a human review stays `in_progress`, with\n`awaiting_human_review` true.","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","flow_id":"550e8400-e29b-41d4-a716-446655440000","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":{"flow_id":{"type":"string","format":"uuid","title":"Flow Id","description":"ID of the flow to execute. The former name `agent_id` is still accepted, and is removed 31 December 2026."},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Values for the flow's inputs, as listed in GET /flows/{id}. Each `id` must be one of those inputs (unknown ids → 400), and every input with `required: true` must be present (missing → 400). An omitted optional input runs with the value saved in the flow."},"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; longer → 422). Unique per organization across runs and app runs: 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= (or GET /app-runs?external_id= when an app run holds it). Use a new id per run."}},"type":"object","required":["flow_id"],"title":"RunCreateRequest","description":"Request to create and start a new flow execution run.","example":{"external_id":"order-4821","flow_id":"550e8400-e29b-41d4-a716-446655440000","inputs":[{"id":"text_input_1","value":"Create a marketing banner for a tech startup"}]}},"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.","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":"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."},"RunSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"flow_id":{"type":"string","format":"uuid","title":"Flow Id","description":"ID of the flow 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.0,"minimum":0.0,"title":"Progress","description":"Rough completion indicator from 0.0 to 1.0 (see `Run.progress`)","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 the run ended (completed, failed, or canceled). Null while in_progress."},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed so far, summed over the run's nodes; null before any node has started"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","flow_id","status","created_at","agent_id"],"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, then waits for another decision on the same review."},"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` (missing → 400). Ignored when decision is `retry`. Must be an object matching the shape of `proposed_output` ({\"asset_ids\": [...]} for image/video/audio reviews, {\"prompts\": [...]} for text reviews — a text node's own key such as `texts` is also accepted); a mismatched shape is rejected with 400. 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 with 400."}},"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"}]},"ApiErrorCode":{"description":"Machine-readable error code, with its usual HTTP status: `invalid_input`\n400, `authentication_required` 401, `forbidden` 403, `not_found` 404,\n`conflict` 409, `validation_error` 422, `rate_limit_exceeded` 429,\n`internal_error` 500, `run_failed` 502, `service_unavailable` 503, `timeout`\n504. A 4xx status without a code of its own is sent as `invalid_input`.\n\n`plan_required`, `credit_usage_exceeded`, `user_quota_exceeded`,\n`spend_limit_exceeded`, `brain_flow_impact`, `stale_definition`,\n`flow_not_shared` and `asset_not_ready` have no status of their own and are\nsent only in the `X-Pletor-Error-Code` response header, never as `code`.","enum":["invalid_input","authentication_required","forbidden","not_found","conflict","validation_error","rate_limit_exceeded","internal_error","run_failed","service_unavailable","timeout","plan_required","credit_usage_exceeded","user_quota_exceeded","spend_limit_exceeded","brain_flow_impact","stale_definition","flow_not_shared","asset_not_ready"],"title":"ApiErrorCode","type":"string"},"ApiErrorDetail":{"description":"Structured details for an API error.","properties":{"code":{"$ref":"#/components/schemas/ApiErrorCode","description":"Machine-readable error code; branch on this, not on `message`"},"message":{"description":"Human-readable error description","title":"Message","type":"string"},"status":{"description":"HTTP status code of this response","title":"Status","type":"integer"},"details":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}]},"description":"Additional context. Always holds `request_id` (the response's `X-Request-Id`); `validation_error` from request validation adds `errors`, a list of `location: message` strings, and `rate_limit_exceeded` adds `retry_after`, the seconds to wait.","title":"Details","type":"object"}},"required":["code","message","status","details"],"title":"ApiErrorDetail","type":"object"},"ApiErrorResponse":{"description":"Standard error response envelope. All API errors follow this format.","example":{"error":{"code":"invalid_input","details":{"request_id":"550e8400-e29b-41d4-a716-446655440000"},"message":"Missing required input 'prompt'","status":400}},"properties":{"error":{"$ref":"#/components/schemas/ApiErrorDetail","description":"Error details"}},"required":["error"],"title":"ApiErrorResponse","type":"object"},"AppV2":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable app identifier"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug","description":"API name of the app, unique in its organization. Usable wherever an app id is"},"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"},"version":{"type":"integer","title":"Version","description":"Version this response describes"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per run at the default settings. 0 when no estimate is available"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when a run pauses on a human review step until a decision is submitted","default":false},"versions":{"items":{"$ref":"#/components/schemas/AppVersion"},"type":"array","title":"Versions","description":"Every published version, newest first"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema of a run's `inputs`, `settings` and `outputs`, keyed by slug. Display names are each field's `title`"},"output_schema":{"additionalProperties":true,"type":"object","title":"Output Schema","description":"JSON Schema of a finished run's `outputs`, keyed by slug. `x-data-type` names each output's kind: text, images, videos, audio, files or data"}},"type":"object","required":["id","slug","name","description","visibility","version","estimated_cost","versions","input_schema","output_schema"],"title":"AppV2","description":"An app with its run contract as JSON Schema.","example":{"description":"A short ad from a product photo and a script","estimated_cost":120,"has_human_review":false,"id":"5f0c2f6e-8f0a-4b8e-9b1e-2c8d6a0fa91e","input_schema":{"properties":{"inputs":{"properties":{"product_photo":{"properties":{"asset_ids":{"items":{"format":"uuid","type":"string"},"maxItems":1,"type":"array"}},"required":["asset_ids"],"title":"Product photo","type":"object"},"script":{"title":"Script","type":"string"}},"required":["product_photo","script"],"type":"object"},"settings":{"properties":{"aspect_ratio":{"default":"9:16","enum":["9:16","16:9","1:1"],"title":"Aspect ratio"}},"type":"object"}},"type":"object"},"name":"Product video ad","output_schema":{"properties":{"video":{"items":{"format":"uuid","type":"string"},"title":"Video","type":"array","x-data-type":"videos"}},"required":["video"],"type":"object"},"slug":"product-video-ad","version":7,"versions":[{"breaking":true,"created_at":"2026-10-12T09:14:00Z","version":7},{"breaking":false,"created_at":"2026-10-02T16:40:00Z","version":6}],"visibility":"workspace"}},"AppV2PendingReview":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Use as `review_id` in POST /apps/{app}/runs/{run_id}/reviews/{review_id}"},"output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Kind of output under review"},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"What the reviewed step produced, e.g. {\"asset_ids\": [...]}. Submit it back, optionally trimmed, as `output` to approve"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the review was opened"}},"type":"object","required":["id","created_at"],"title":"AppV2PendingReview","description":"A human review step waiting for a decision."},"AppV2Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Run identifier"},"app_id":{"type":"string","format":"uuid","title":"App Id","description":"Stable ID of the app"},"version":{"type":"integer","title":"Version","description":"App version the run executes"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Your reference, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"in_progress, then exactly one of completed, failed or canceled"},"progress":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Progress","description":"Fraction of steps completed","default":0.0},"awaiting_human_review":{"type":"boolean","title":"Awaiting Human Review","description":"True while paused on a human review step","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 it started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When it ended; null while in_progress"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits used so far; null before any step ran"},"pending_reviews":{"items":{"$ref":"#/components/schemas/AppV2PendingReview"},"type":"array","title":"Pending Reviews","description":"Review steps waiting for a decision; empty unless `awaiting_human_review`"},"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"The run's input values, keyed by slug"},"outputs":{"additionalProperties":true,"type":"object","title":"Outputs","description":"Each output's value, keyed by slug, as `output_schema` describes. An output appears once it is produced, so this fills in while in_progress. Media values are asset IDs: GET /assets/{id} resolves them"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message when the run failed or was canceled"},"failure_reason":{"anyOf":[{"$ref":"#/components/schemas/FailureReason"},{"type":"null"}],"description":"Categorized cause when failed or canceled"}},"type":"object","required":["id","app_id","version","status","created_at"],"title":"AppV2Run","description":"A run with its inputs and outputs, keyed by slug."},"AppV2RunCreateRequest":{"properties":{"version":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Version","description":"App version to run. Omitted runs the latest version when the run starts; a pinned run keeps that version's inputs, settings, outputs and flow after the app is republished"},"inputs":{"additionalProperties":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"}]},"type":"object","title":"Inputs","description":"Input values keyed by slug, as `input_schema.properties.inputs` describes. Text takes a string or a list of strings; media takes {\"asset_ids\": [...]}"},"settings":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"},{"type":"number"}]},"type":"object","title":"Settings","description":"Setting values keyed by slug. Omitted settings use their default"},"outputs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Outputs","description":"Output slugs to produce. Omitted produces every output; required outputs are always produced"},"external_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"External Id","description":"Your own reference for this run (max 255 chars), unique per organization: reusing one answers 409, so a retried request never starts a second run"}},"additionalProperties":false,"type":"object","title":"AppV2RunCreateRequest","description":"Request to start a run of an app.","example":{"external_id":"order-1042","inputs":{"product_photo":{"asset_ids":["c41e8a52-1f0b-4a57-9d1e-6b2f0c8e07b2"]},"script":"Meet the lightest trail shoe yet."},"settings":{"aspect_ratio":"9:16"}}},"AppV2RunSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Run identifier"},"app_id":{"type":"string","format":"uuid","title":"App Id","description":"Stable ID of the app"},"version":{"type":"integer","title":"Version","description":"App version the run executes"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Your reference, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"in_progress, then exactly one of completed, failed or canceled"},"progress":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Progress","description":"Fraction of steps completed","default":0.0},"awaiting_human_review":{"type":"boolean","title":"Awaiting Human Review","description":"True while paused on a human review step","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 it started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When it ended; null while in_progress"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits used so far; null before any step ran"}},"type":"object","required":["id","app_id","version","status","created_at"],"title":"AppV2RunSummary","description":"A run as listed by GET /apps/{app}/runs."},"AppV2Summary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable app identifier"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug","description":"API name of the app, unique in its organization. Usable wherever an app id is"},"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"},"version":{"type":"integer","title":"Version","description":"Latest version number"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per run at the default settings. 0 when no estimate is available"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when a run pauses on a human review step until a decision is submitted","default":false}},"type":"object","required":["id","slug","name","description","visibility","version","estimated_cost"],"title":"AppV2Summary","description":"An app as listed by GET /apps."},"AppVersion":{"properties":{"version":{"type":"integer","title":"Version","description":"Version number, starting at 1"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When this version was published"},"breaking":{"type":"boolean","title":"Breaking","description":"True when a caller of the previous version has to change something to call this one: a field removed or renamed, a new required input, fewer accepted values, a changed type. Pin `version` to keep calling the previous one"}},"type":"object","required":["version","created_at","breaking"],"title":"AppVersion","description":"One published version of an app."},"CursorPaginatedResponse_AppV2RunSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AppV2RunSummary"},"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[AppV2RunSummary]"},"CursorPaginatedResponse_AppV2Summary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AppV2Summary"},"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[AppV2Summary]"}},"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"}}}}