Aıon

Documentation

Agents API Reference

Direct access to AI agents for search, synthesis, analysis, and file organization without chat sessions

Stateless Agent Access

These endpoints provide direct, stateless access to AI agents without requiring chat sessions. Each call executes a single operation and returns self-contained results — ideal for programmatic integrations, agentic pipelines, and building custom interfaces.

How It Works

  • • Intelligent Reasoning: The AI iteratively refines results until they are satisfactory
  • • Adaptive Strategy: Approach is automatically optimized based on your query
  • • Structured Responses: Consistent request/response format for every operation
  • • Usage Tracking: Every response includes execution time and token usage

Search

AI-powered search with intelligent reasoning, multi-match boosting, and feature filtering.

Image Search

POST/api/v2/agents/search/images

Execute AI-powered image search with intelligent reasoning

Request

{
  "query": "damaged utility poles in residential areas",
  "limit": 50,
  "folder_id": "550e8400-e29b-41d4-a716-446655440000",
  "image_ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"]
}


// Parameters:
// - query: 1-2000 chars - natural language search query
// - limit: 1-500, default 50 (advisory - AI may return fewer based on relevance)
// - folder_id: Optional - restrict to specific folder
// - image_ids: Optional - search within specific images

Response

{
  "success": true,
  "results": [
    {
      "image_id": "550e8400-e29b-41d4-a716-446655440000",
      "score": 0.92,
      "filename": "pole_damage_01.jpg",
      "title": "Utility Pole Assessment",
      "description": "Damaged wooden utility pole with visible crack...",
      "folder_id": "folder_abc123",
      "thumbnail_url": "https://cdn.aionvision.tech/thumbs/...",
      "features": [
        {"name": "utility_pole", "items": [{"count": 1, "confidence": 0.95}]},
        {"name": "damage", "items": [{"count": 1, "confidence": 0.88}]}
      ]
    }
  ],
  "count": 15,
  "result_ids": ["550e8400-...", "660f9500-...", ...],
  "summary": "Found 15 images of damaged utility poles",
  "summary_raw": "Found [[ref:search_1]] images of damaged utility poles",
  "result_refs": {
    "search_1": {
      "count": 15,
      "ids": ["550e8400-...", ...],
      "image_ids": ["550e8400-...", ...],
      "id_type": "image",
      "label": "15 images"
    }
  },
  "search_strategy": {"mode": "semantic", "reranking": true},
  "execution_time_ms": 1250,
  "iterations": 2,
  "token_usage": {"input": 450, "output": 280}
}

Document Search

POST/api/v2/agents/search/documents

Execute AI-powered document search with intelligent reasoning

Request

{
  "query": "safety inspection procedures for electrical equipment",
  "limit": 50,
  "document_types": ["pdf", "docx"],
  "document_ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"]
}


// Parameters:
// - query: 1-2000 chars - natural language search query
// - limit: 1-500, default 50 (advisory)
// - document_types: Optional - filter by type (pdf, docx, txt)
// - document_ids: Optional - search within specific documents

Response

{
  "success": true,
  "results": [
    {
      "chunk_id": "chunk_550e8400",
      "document_id": "doc_550e8400",
      "document_filename": "safety_manual.pdf",
      "text": "Electrical equipment inspections must be conducted quarterly...",
      "score": 0.89,
      "page_numbers": [12, 13],
      "chunk_index": 5
    }
  ],
  "count": 8,
  "chunk_ids": ["chunk_550e8400", "chunk_660f9500", ...],
  "document_ids": ["doc_550e8400", "doc_660f9500"],
  "summary": "Found 8 relevant sections across 2 documents",
  "summary_raw": "Found [[ref:search_1]] relevant sections across [[ref:docs_1]] documents",
  "result_refs": {
    "search_1": {
      "count": 8,
      "ids": ["chunk_550e8400", ...],
      "image_ids": [],
      "id_type": "chunk",
      "label": "8 sections"
    },
    "docs_1": {
      "count": 2,
      "ids": ["doc_550e8400", "doc_660f9500"],
      "image_ids": [],
      "id_type": "document",
      "label": "2 documents"
    }
  },
  "search_mode": "hybrid",
  "search_strategy": {"mode": "hybrid", "reranking": true},
  "execution_time_ms": 980,
  "iterations": 1,
  "token_usage": {"input": 320, "output": 180}
}

Operations

Stateless access to synthesis, document analysis, and file organization agents. Each endpoint executes the underlying agent and returns a self-contained result.

Synthesize Report

POST/api/v2/agents/synthesize

Generate a report or summary from images and documents using the synthesis agent

Request

{
  "intent": "Write a report comparing Q3 and Q4 spending patterns",
  "image_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "document_ids": ["660f9500-e29b-41d4-a716-446655440000"],
  "auto_save": true
}


// Parameters:
// - intent: 1-2000 chars - what to synthesize (required)
// - image_ids: Optional - images to include in synthesis
// - document_ids: Optional - documents to include in synthesis
// - auto_save: Optional (default false) - save the report as a new document

Response

{
  "success": true,
  "report": "# Q3 vs Q4 Spending Analysis\n\n## Overview\n\nBased on the provided documents...",
  "summary": "Comparative analysis of Q3 and Q4 spending across 3 categories",
  "image_count": 1,
  "document_count": 1,
  "saved_document_id": "770a0600-e29b-41d4-a716-446655440000",
  "execution_time_ms": 4200,
  "iterations": 3,
  "token_usage": {"input": 1250, "output": 890}
}

Analyze Documents

POST/api/v2/agents/analyze/documents

Perform deep analysis on documents: summarize, compare, and categorize

Request

{
  "intent": "Summarize and compare these two contracts, highlighting key differences",
  "document_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660f9500-e29b-41d4-a716-446655440000"
  ]
}


// Parameters:
// - intent: 1-2000 chars - analysis intent (required)
// - document_ids: At least one document ID (required)

Response

{
  "success": true,
  "analysis": "# Contract Comparison\n\n## Key Differences\n\n1. **Term Length**: Contract A is 12 months...",
  "summary": "Compared 2 contracts with 5 key differences in terms, liability, and pricing",
  "document_count": 2,
  "categorization": {
    "type": "legal_contract",
    "subtypes": ["service_agreement", "vendor_contract"]
  },
  "chunk_references": [
    {
      "chunk_id": "chunk_abc123",
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "document_filename": "contract_a.pdf",
      "page_numbers": [3, 4]
    },
    {
      "chunk_id": "chunk_def456",
      "document_id": "660f9500-e29b-41d4-a716-446655440000",
      "document_filename": "contract_b.pdf",
      "page_numbers": [2, 5]
    }
  ],
  "execution_time_ms": 3800,
  "iterations": 2,
  "token_usage": {"input": 980, "output": 720}
}

Organize Files

POST/api/v2/agents/organize

Organize files into folders using AI-driven categorization

Request

{
  "intent": "Sort these files by project and document type",
  "image_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660f9500-e29b-41d4-a716-446655440000"
  ],
  "document_ids": [
    "770a0600-e29b-41d4-a716-446655440000"
  ],
  "parent_folder_id": "880b1700-e29b-41d4-a716-446655440000"
}


// Parameters:
// - intent: 1-2000 chars - organization intent (required)
// - image_ids: Optional - images to organize
// - document_ids: Optional - documents to organize
// - parent_folder_id: Optional - parent folder for newly created folders

Response

{
  "success": true,
  "summary": "Created 2 folders and organized 3 files by project type",
  "actions": [
    {
      "action": "create_and_move_files",
      "folder_id": "new_folder_001",
      "folder_name": "Site Inspections",
      "file_count": 2
    },
    {
      "action": "create_and_move_files",
      "folder_id": "new_folder_002",
      "folder_name": "Contracts",
      "file_count": 1
    }
  ],
  "folders_created": 2,
  "files_moved": 3,
  "execution_time_ms": 2100,
  "iterations": 2,
  "token_usage": {"input": 680, "output": 420}
}

Pipeline

Chain multiple agent steps into a single server-side execution with automatic data wiring and parallel execution.

Execute Pipeline

POST/api/v2/agents/pipeline

Execute a multi-step agent pipeline with automatic data wiring

Request

{
  "steps": [
    {
      "agent": "image_search",
      "intent": "find damaged utility poles"
    },
    {
      "agent": "folder",
      "intent": "sort by damage severity"
    }
  ],
  "image_ids": null,
  "document_ids": null
}


// Parameters:
// - steps: 1-10 agent steps (required)
//   - agent: Agent name (see list below)
//   - intent: 1-2000 chars - natural language description
//   - depends_on: Optional list of 0-based step indices
// - image_ids: Optional - seed pipeline with image UUIDs
// - document_ids: Optional - seed pipeline with document UUIDs
//
// Agent names: image_search, document_search, link_search,
//   analysis, document_analysis, link_analysis,
//   assistant, folder, cross_reference, analytics, chat
//
// When depends_on is omitted, steps are auto-wired by data type.
// When specified, steps execute in parallel waves where possible.

Response

{
  "success": true,
  "nodes": [
    {
      "node_id": "a1b2c3d4",
      "agent": "image_search",
      "status": "completed",
      "summary": "Found 23 images of damaged utility poles",
      "outputs": {},
      "error": null,
      "execution_time_ms": 1450
    },
    {
      "node_id": "e5f6g7h8",
      "agent": "folder",
      "status": "completed",
      "summary": "Created 3 folders and organized 23 files by damage severity",
      "outputs": {},
      "error": null,
      "execution_time_ms": 2100
    }
  ],
  "execution_time_ms": 3680,
  "total_waves": 2,
  "errors": [],
  "token_usage": {"input": 850, "output": 520}
}

DAG Example

Use depends_on for parallel fan-in patterns. Steps without shared dependencies execute in the same wave:

{
  "steps": [
    {"agent": "image_search", "intent": "utility poles"},
    {"agent": "document_search", "intent": "inspection reports"},
    {"agent": "assistant", "intent": "Cross-reference findings", "depends_on": [0, 1]}
  ]
}

Related

Semantic Search Guide

Using AI-powered search

Chat Reference

Interactive AI conversations

Documents Reference

Document management and chunk search

Folders Reference

Manual folder management