Agents

Agents represent specific AI-powered capabilities — on-brand photo generation, UGC video generation, static ads generation, and more. Use these endpoints to discover available agents and inspect their required inputs and expected outputs.

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

List Agents

get

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.

Authorizations

APIKeyHeader

Query parameters

tagsstring[] · nullableOptional

searchstring · nullableOptional

Search agents by name

limitinteger · min: 1 · max: 100Optional

Maximum number of items to return

Default: 20

cursorstring · nullableOptional

Cursor for pagination (from next_cursor)

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

has_morebooleanRequired

next_cursorstring · nullableOptional

422

Validation Error

application/json

get/agents/

HTTPcURLJavaScriptPython

GET /api/public/v1/agents/ HTTP/1.1
Host: api.pletor.ai
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "tags": [
        "text"
      ],
      "estimated_cost": 1,
      "visibility": "public",
      "inputs": [
        {
          "id": "text",
          "type": "text_input",
          "description": "text",
          "required": true
        }
      ],
      "has_human_review": false
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Get Agent

get

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

Authorizations

APIKeyHeader

Path parameters

agent_idstring · uuidRequired

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

Complete representation of an AI agent with its inputs, outputs, and cost.

idstring · uuidRequired

Unique agent identifier

namestringRequired

Agent display name

descriptionstringRequired

Agent description and purpose

tagsstring[]Optional

Categorization tags for filtering

estimated_costintegerRequired

Estimated credit cost per execution

has_human_reviewbooleanOptional

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

422

Validation Error

application/json

get/agents/{agent_id}

HTTPcURLJavaScriptPython

GET /api/public/v1/agents/{agent_id} HTTP/1.1
Host: api.pletor.ai
Accept: */*

{
  "description": "Generate marketing banners from a text prompt and logo",
  "estimated_cost": 50,
  "has_human_review": false,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inputs": [
    {
      "description": "Product description",
      "id": "uuid-1",
      "required": true,
      "type": "text_input"
    },
    {
      "description": "Company logo",
      "id": "uuid-2",
      "required": false,
      "type": "image_input"
    }
  ],
  "name": "Marketing Banner Generator",
  "outputs": [
    {
      "description": "Generated banner",
      "id": "uuid-3",
      "type": "images"
    }
  ],
  "tags": [
    "marketing",
    "image"
  ]
}