Scopix

Documentation

Agents API Reference

Direct access to AI agents for search, synthesis, and analysis 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

json
{
  "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"],
  "domain": "civil_engineering"
}


// 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
// - domain: Optional - domain context: general, civil_engineering, maps, mining

Response

json
{
  "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.scopix.ai/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:1]] showing damaged utility poles",
  "result_refs": {
    "1": {"count": 15, "ids": ["550e8400-...", "660f9500-..."], "image_ids": ["550e8400-...", "660f9500-..."], "id_type": "image", "label": "damaged poles"}
  },
  "search_mode": "hybrid",
  "search_strategy": null,
  "execution_time_ms": 1250,
  "iterations": 2,
  "token_usage": {"input_tokens": 450, "output_tokens": 280, "total_tokens": 730}
}

Document Search

POST/api/v2/agents/search/documents

Execute AI-powered document search with intelligent reasoning

Request

json
{
  "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"],
  "domain": "civil_engineering"
}


// 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
// - domain: Optional - domain context: general, civil_engineering, maps, mining

Response

json
{
  "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:1]] and [[ref:2]] across 2 documents",
  "result_refs": {
    "1": {"count": 3, "ids": ["chunk_550e8400", "chunk_660f9500", "chunk_770a6600"], "image_ids": [], "id_type": "chunk", "label": "safety procedures"},
    "2": {"count": 2, "ids": ["chunk_880b7700", "chunk_990c8800"], "image_ids": [], "id_type": "chunk", "label": "equipment specs"}
  },
  "search_mode": "hybrid",
  "search_strategy": null,
  "execution_time_ms": 980,
  "iterations": 1,
  "token_usage": {"input_tokens": 320, "output_tokens": 180, "total_tokens": 500}
}

Video Search

POST/api/v2/agents/search/videos

Execute AI-powered video search with scene-level matching and per-scene timestamps

Request

json
{
  "query": "closeup of a fire truck at night",
  "limit": 50,
  "folder_id": "550e8400-e29b-41d4-a716-446655440010",
  "video_ids": ["vid_550e8400", "vid_660f9500"],
  "domain": "general"
}


// Parameters:
// - query: 1-2000 chars - natural language search query
// - limit: 1-500, default 50 (advisory)
// - folder_id: Optional - restrict search to a single folder
// - video_ids: Optional - restrict search to specific videos
// - domain: Optional - domain context: general, civil_engineering, maps, mining

Response

json
{
  "success": true,
  "results": [
    {
      "video_id": "vid_550e8400",
      "video_filename": "engine-7-night-run.mp4",
      "score": 0.91,
      "video_description": "Night ride-along footage from Engine 7",
      "duration_seconds": 612.4,
      "resolution": "1920x1080",
      "thumbnail_url": "https://cdn.scopix.ai/thumbnails/vid_550e8400.jpg",
      "matched_scenes": [
        {
          "scene_id": "scn_abc123",
          "scene_index": 14,
          "start_time": 423.5,
          "end_time": 431.2,
          "time_range_formatted": "00:07:03-00:07:11",
          "description": "Closeup of engine 7 pumping at a two-story fire",
          "score": 0.93,
          "tags": ["fire_truck", "night", "pumping"],
          "thumbnail_url": "https://cdn.scopix.ai/scenes/scn_abc123.jpg"
        }
      ]
    }
  ],
  "count": 3,
  "video_ids": ["vid_550e8400", "vid_660f9500", "vid_770a6600"],
  "summary": "Found 3 videos with scenes matching the query.",
  "summary_raw": "Found [[ref:1]] videos with matching scenes.",
  "result_refs": {
    "1": {"count": 3, "ids": ["vid_550e8400", "vid_660f9500", "vid_770a6600"], "image_ids": [], "id_type": "video", "label": "fire truck closeups"}
  },
  "search_mode": "hybrid",
  "search_strategy": null,
  "execution_time_ms": 1120,
  "iterations": 1,
  "token_usage": {"input_tokens": 340, "output_tokens": 180, "total_tokens": 520}
}

Operations

Stateless access to synthesis and document analysis 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

json
{
  "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

json
{
  "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_tokens": 1250, "output_tokens": 890, "total_tokens": 2140}
}

Analyze Documents

POST/api/v2/agents/analyze/documents

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

Request

json
{
  "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

json
{
  "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_tokens": 980, "output_tokens": 720, "total_tokens": 1700}
}

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 scheduled into topological waves

Request

json
{
  "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 (forward refs only)
// - 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 on every step, steps run in input order
// (one per wave). When specified on any step, Kahn's algorithm groups
// independent steps into parallel waves. Per-step results are returned
// in input order regardless of execution order.
//
// Same-type fan-in (two parallel parents producing the same content type
// into one downstream step) is rejected at validation time.

Response

json
{
  "success": true,
  "nodes": [
    {
      "node_id": "a1b2c3d4",
      "agent": "image_search",
      "status": "completed",
      "summary": "Found 23 images of damaged utility poles",
      "outputs": {},
      "error_message": 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_message": null,
      "execution_time_ms": 2100
    }
  ],
  "execution_time_ms": 3680,
  "total_waves": 2,
  "errors": [],
  "token_usage": {"input_tokens": 850, "output_tokens": 520, "total_tokens": 1370}
}

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

Files Reference

File and document management

Folders Reference

Manual folder management