> 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/agents.md).

# Agents

Discover AI agents and inspect their input requirements and output types.

## List Agents

> List available AI agents with filtering options.\
> \
> This endpoint returns a paginated list of AI agents that can generate various types of\
> content including images, videos, text, and other creative assets.\
> \
> \*\*Filtering Options:\*\*\
> \- \`tags\`: Filter agents by tags (can be provided multiple times)\
> \- \`visibility\`: Filter agents by their visibility status (can be provided multiple times)\
>    Options include:\
>     \- PRIVATE: Internal organization's agents\
>     \- SHARED: Agents shared by the user\
>     \- PUBLIC: Pletor public agents\
>    By default, only PRIVATE and SHARED agents are returned.\
> \- \`search\`: Search agents by name (case-insensitive)\
> \
> \*\*Pagination Parameters:\*\*\
> \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\
> \- \`cursor\`: Cursor for pagination (optional)\
> \
> \*\*Response:\*\*\
> \- \`data\`: List of agent summaries with basic information including expected inputs\
> \- \`has\_more\`: Indicates if there are more results available\
> \- \`next\_cursor\`: Cursor for the next page of results\
> \
> \*\*Use Case:\*\* This is typically the first endpoint called to discover available agents\
> before getting detailed information or executing them.

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"agents","description":"Discover AI agents and inspect their input requirements and output types."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"FlowVisibility":{"type":"string","enum":["public","shared","private"],"title":"FlowVisibility","description":"Visibility levels for workflows."},"CursorPaginatedResponse_AgentSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AgentSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[AgentSummary]"},"AgentSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique agent identifier"},"name":{"type":"string","title":"Name","description":"Agent display name"},"description":{"type":"string","title":"Description","description":"Agent description and purpose"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Categorization tags for filtering"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"},"visibility":{"$ref":"#/components/schemas/FlowVisibility","description":"Visibility level: PRIVATE, SHARED, or PUBLIC"},"inputs":{"items":{"$ref":"#/components/schemas/AgentInput"},"type":"array","title":"Inputs","description":"All inputs for this agent; check the `required` flag on each to determine which are mandatory"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when this agent includes a human review step that will pause execution until resolved via POST /runs/{run_id}/reviews/{review_id}. Poll GET /runs/{run_id} for `awaiting_human_review` while the run is in progress.","default":false}},"type":"object","required":["id","name","description","estimated_cost","visibility"],"title":"AgentSummary","description":"Lightweight agent summary for list views."},"AgentInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/NodeType","description":"Input type: text_input, image_input, video_input, file_input, etc."},"description":{"type":"string","title":"Description","description":"Human-readable description of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input must be provided when creating a run","default":true}},"type":"object","required":["id","type","description"],"title":"AgentInput","description":"Represents an input requirement for an agent."},"NodeType":{"type":"string","enum":["text_input","image_input","file_input","video_input","audio_input","brand_system_input","llm","image_generation","video_generation","text_to_speech","screen_mockup","remove_background","upscale","upscale_video","video_background_removal","extract_video_frame","image_generation_lora","change_aspect_ratio","meta_ads_extractor","image_edit","vectorize","image_erase","linkedin_ads_extractor","instagram_posts_extractor","linkedin_posts_extractor","human_review","match_brand_colors","tiktok_extractor","add_logo","video_subtitle","video_concat","video_add_sound","generic_fal","comment","group","composer","googledrive_find_file","googledrive_upload_file","prompt_concatenate","text_split","list_selector","video_edit","router","camera_angle","rename_asset","music_generation","merge_audio_video","trim_speed","extract_audio","remove_audio","isolate_sound","clone_voice","translate_audio","translate_video","transcribe"],"title":"NodeType"},"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":{"/agents/":{"get":{"tags":["agents"],"summary":"List Agents","description":"List available AI agents with filtering options.\n\nThis endpoint returns a paginated list of AI agents that can generate various types of\ncontent including images, videos, text, and other creative assets.\n\n**Filtering Options:**\n- `tags`: Filter agents by tags (can be provided multiple times)\n- `visibility`: Filter agents by their visibility status (can be provided multiple times)\n   Options include:\n    - PRIVATE: Internal organization's agents\n    - SHARED: Agents shared by the user\n    - PUBLIC: Pletor public agents\n   By default, only PRIVATE and SHARED agents are returned.\n- `search`: Search agents by name (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 agent 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 agents\nbefore getting detailed information or executing them.","operationId":"list_agents_agents__get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Tags"}},{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FlowVisibility"}},{"type":"null"}],"title":"Visibility"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search agents by name","title":"Search"},"description":"Search agents by name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_AgentSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Agent

> Get detailed information about a specific AI agent.\
> \
> This endpoint retrieves comprehensive information about an AI agent, including:\
> \- Agent metadata (name, description, category, tags)\
> \- Input requirements with types\
> \- Output specifications and formats\
> \- Performance metrics and cost estimates\
> \
> \*\*Input Information:\*\*\
> Each agent defines specific inputs it requires:\
> \- \`id\`: Node identifier used when executing the agent\
> \- \`type\`: Input type (text\_input, image\_input, video\_input, file\_input)\
> \- \`description\`: Description of what this input does\
> \
> \*\*Output Information:\*\*\
> Each agent specifies what types of content it generates:\
> \- \`id\`: Node identifier for the output\
> \- \`type\`: Output type (text, images, videos, files, data)\
> \- \`description\`: Description of what this output contains\
> \
> \*\*Performance Metrics:\*\*\
> \- \`estimated\_cost\`: Credit cost estimation for running this agent\
> \
> \*\*Use Case:\*\* Call this endpoint to understand what inputs an agent needs and what\
> outputs it will generate before creating a generation request.\
> \
> \*\*Error Codes:\*\*\
> \- \`404\`: Agent not found or not accessible\
> \- \`422\`: Agent has no active version

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"agents","description":"Discover AI agents and inspect their input requirements and output types."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"Agent":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique agent identifier"},"name":{"type":"string","title":"Name","description":"Agent display name"},"description":{"type":"string","title":"Description","description":"Agent description and purpose"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Categorization tags for filtering"},"inputs":{"items":{"$ref":"#/components/schemas/AgentInput"},"type":"array","title":"Inputs","description":"All inputs for this agent. Use these IDs when creating a run; check the `required` flag on each input to determine which are mandatory"},"outputs":{"items":{"$ref":"#/components/schemas/AgentOutput"},"type":"array","title":"Outputs","description":"Expected outputs. Match these IDs in run results"},"estimated_cost":{"type":"integer","title":"Estimated Cost","description":"Estimated credit cost per execution"},"has_human_review":{"type":"boolean","title":"Has Human Review","description":"True when this agent includes a human review step that will pause execution until resolved via POST /runs/{run_id}/reviews/{review_id}. Poll GET /runs/{run_id} for `awaiting_human_review` while the run is in progress.","default":false}},"type":"object","required":["id","name","description","estimated_cost"],"title":"Agent","description":"Complete representation of an AI agent with its inputs, outputs, and cost."},"AgentInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to use when providing this input"},"type":{"$ref":"#/components/schemas/NodeType","description":"Input type: text_input, image_input, video_input, file_input, etc."},"description":{"type":"string","title":"Description","description":"Human-readable description of this input"},"required":{"type":"boolean","title":"Required","description":"Whether this input must be provided when creating a run","default":true}},"type":"object","required":["id","type","description"],"title":"AgentInput","description":"Represents an input requirement for an agent."},"NodeType":{"type":"string","enum":["text_input","image_input","file_input","video_input","audio_input","brand_system_input","llm","image_generation","video_generation","text_to_speech","screen_mockup","remove_background","upscale","upscale_video","video_background_removal","extract_video_frame","image_generation_lora","change_aspect_ratio","meta_ads_extractor","image_edit","vectorize","image_erase","linkedin_ads_extractor","instagram_posts_extractor","linkedin_posts_extractor","human_review","match_brand_colors","tiktok_extractor","add_logo","video_subtitle","video_concat","video_add_sound","generic_fal","comment","group","composer","googledrive_find_file","googledrive_upload_file","prompt_concatenate","text_split","list_selector","video_edit","router","camera_angle","rename_asset","music_generation","merge_audio_video","trim_speed","extract_audio","remove_audio","isolate_sound","clone_voice","translate_audio","translate_video","transcribe"],"title":"NodeType"},"AgentOutput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID to match in run results"},"type":{"$ref":"#/components/schemas/DataType","description":"Output data type: text, images, videos, files, audio, or data"},"description":{"type":"string","title":"Description","description":"Human-readable description of this output"}},"type":"object","required":["id","type","description"],"title":"AgentOutput","description":"Represents an output produced by an agent."},"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":{"/agents/{agent_id}":{"get":{"tags":["agents"],"summary":"Get Agent","description":"Get detailed information about a specific AI agent.\n\nThis endpoint retrieves comprehensive information about an AI agent, including:\n- Agent metadata (name, description, category, tags)\n- Input requirements with types\n- Output specifications and formats\n- Performance metrics and cost estimates\n\n**Input Information:**\nEach agent defines specific inputs it requires:\n- `id`: Node identifier used when executing the agent\n- `type`: Input type (text_input, image_input, video_input, file_input)\n- `description`: Description of what this input does\n\n**Output Information:**\nEach agent specifies what types of content it generates:\n- `id`: Node identifier for the output\n- `type`: Output type (text, images, videos, files, data)\n- `description`: Description of what this output contains\n\n**Performance Metrics:**\n- `estimated_cost`: Credit cost estimation for running this agent\n\n**Use Case:** Call this endpoint to understand what inputs an agent needs and what\noutputs it will generate before creating a generation request.\n\n**Error Codes:**\n- `404`: Agent not found or not accessible\n- `422`: Agent has no active version","operationId":"get_agent_agents__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```