> For the complete documentation index, see [llms.txt](https://docs.pletor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pletor.ai/documentation/api-reference/apps.md).

# Apps

Discover and inspect runnable apps built on flows.

## List Apps

> List available apps with filtering options.\
> \
> Apps are curated, runnable applications built on top of flows. Each app exposes a\
> set of configured inputs and produces one or more outputs, and can be executed\
> directly via \`POST /app-runs\`.\
> \
> \*\*Filtering Options:\*\*\
> \- \`visibility\`: Filter apps by their visibility status (can be provided multiple times)\
>    Options include:\
>     \- private: Only visible to the creator\
>     \- workspace: Visible to everyone in the creator's organization\
>     \- shared: Visible via a shared link\
>     \- public: Visible to everyone\
>    By default, all apps accessible to the caller are returned.\
> \- \`search\`: Search apps by name or description (case-insensitive)\
> \
> \*\*Pagination Parameters:\*\*\
> \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\
> \- \`cursor\`: Cursor for pagination (optional)\
> \
> \*\*Response:\*\*\
> \- \`data\`: List of app summaries with basic information including expected inputs\
> \- \`has\_more\`: Indicates if there are more results available\
> \- \`next\_cursor\`: Cursor for the next page of results\
> \
> \*\*Use Case:\*\* This is typically the first endpoint called to discover available apps\
> before getting detailed information or executing them.

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"apps","description":"Discover and inspect runnable apps built on flows."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","shared","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"CursorPaginatedResponse_AppSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AppSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[AppSummary]"},"AppSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable app identifier"},"name":{"type":"string","title":"Name","description":"App display name"},"description":{"type":"string","title":"Description","description":"App description and purpose"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"Public CDN URL for the app thumbnail image"},"visibility":{"$ref":"#/components/schemas/FlowApplicationVisibility","description":"Visibility level: private, workspace, shared, or public"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"},"inputs":{"items":{"$ref":"#/components/schemas/AppInput"},"type":"array","title":"Inputs","description":"Required inputs for this app"}},"type":"object","required":["id","name","description","visibility","estimated_cost"],"title":"AppSummary","description":"Lightweight app summary for list views."},"AppInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/AppInputType","description":"Input type: text, image, video, audio, brand, or file"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options","description":"Allowed values when the input is a fixed set: label strings for text inputs, asset IDs for media inputs"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input"}},"type":"object","required":["id","type","name","required"],"title":"AppInput","description":"Represents an input requirement for an app."},"AppInputType":{"type":"string","enum":["text","image","video","audio","brand","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/apps/":{"get":{"tags":["apps"],"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**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 via a shared 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-insensitive)\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.","operationId":"list_apps_apps__get","parameters":[{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FlowApplicationVisibility"}},{"type":"null"}],"title":"Visibility"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search apps by name or description","title":"Search"},"description":"Search apps by name or description"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_AppSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get App

> Get detailed information about a specific app.\
> \
> This endpoint retrieves comprehensive information about an app, including:\
> \- App metadata (name, description, avatar, visibility)\
> \- Input requirements with types\
> \- Output specifications and formats\
> \- Estimated cost per execution\
> \
> \*\*Input Information:\*\*\
> Each app defines specific inputs it requires:\
> \- \`id\`: Node identifier used when executing the app\
> \- \`type\`: Input type (text, image, video, audio, brand, file)\
> \- \`name\`: Display name of this input\
> \- \`required\`: Whether the input is mandatory\
> \- \`options\`, \`min\_selections\`, \`max\_selections\`: Constraints for fixed-set inputs\
> \
> \*\*Output Information:\*\*\
> Each app specifies what types of content it generates:\
> \- \`id\`: Node identifier for the output\
> \- \`type\`: Output type (text, images, videos, files, audio, data)\
> \- \`description\`: Description of what this output contains\
> \
> \*\*Performance Metrics:\*\*\
> \- \`estimated\_cost\`: Credit cost estimation for running this app\
> \
> \*\*Use Case:\*\* Call this endpoint to understand what inputs an app needs and what\
> outputs it will generate before creating a run.\
> \
> \*\*Error Codes:\*\*\
> \- \`404\`: App not found or not accessible\
> \- \`422\`: App has no associated flow definition

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"apps","description":"Discover and inspect runnable apps built on flows."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"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":"Required inputs for this app. Use these IDs when creating a run"},"outputs":{"items":{"$ref":"#/components/schemas/AppOutput"},"type":"array","title":"Outputs","description":"Expected outputs. Match these IDs in run results"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"}},"type":"object","required":["id","name","description","visibility","estimated_cost"],"title":"App","description":"Complete representation of a runnable app with its inputs, outputs, and cost."},"FlowApplicationVisibility":{"type":"string","enum":["private","workspace","shared","public"],"title":"FlowApplicationVisibility","description":"Visibility levels for flow applications."},"AppInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/AppInputType","description":"Input type: text, image, video, audio, brand, or file"},"name":{"type":"string","title":"Name","description":"Display name of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input is mandatory"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options","description":"Allowed values when the input is a fixed set: label strings for text inputs, asset IDs for media inputs"},"min_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Selections","description":"Minimum number of values the caller must provide for this input"},"max_selections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Selections","description":"Maximum number of values the caller may provide for this input"}},"type":"object","required":["id","type","name","required"],"title":"AppInput","description":"Represents an input requirement for an app."},"AppInputType":{"type":"string","enum":["text","image","video","audio","brand","file"],"title":"AppInputType","description":"Types of inputs an app can accept from a caller."},"AppOutput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to match in run results"},"type":{"$ref":"#/components/schemas/DataType","description":"Output data type: text, images, videos, files, audio, or data"},"description":{"type":"string","title":"Description","description":"Human-readable description of this output"}},"type":"object","required":["id","type","description"],"title":"AppOutput","description":"Represents an output produced by an app."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/apps/{app_id}":{"get":{"tags":["apps"],"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**Input Information:**\nEach app defines specific inputs it requires:\n- `id`: Node identifier used when executing the app\n- `type`: Input type (text, image, video, audio, brand, 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\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, files, audio, data)\n- `description`: Description of what this output contains\n\n**Performance Metrics:**\n- `estimated_cost`: Credit cost estimation for running this app\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- `404`: App not found or not accessible\n- `422`: App has no associated flow definition","operationId":"get_app_apps__app_id__get","parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"App Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/App"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```