> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wesog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Get started with Wesog Search asset management

Wesog Search provides a comprehensive API for managing your image assets with full CRUD operations (Create, Read, Update, Delete). This guide covers the essential concepts and best practices for effective asset management.

## Quick Start

<CardGroup cols={3}>
  <Card title="Upload images" icon="plus" href="/content/search/manage-upload">
    Upload new images to Wesog Search
  </Card>

  <Card title="Update images" icon="pen" href="/content/search/manage-update">
    Update existing image metadata
  </Card>

  <Card title="Delete images" icon="minus" href="/content/search/manage-delete">
    Delete images from Wesog Search
  </Card>
</CardGroup>

## Operations Overview

All operations support both single image and **batch processing** for efficient management of large image collections.

| Operation              | Endpoint       | Required Fields | Optional Fields       | Purpose                   |
| ---------------------- | -------------- | --------------- | --------------------- | ------------------------- |
| Upload new images      | `POST /imgs`   | `id`, `src`     | Image metadata fields | Add images to the system  |
| Update existing images | `PUT /imgs`    | `id`            | Image metadata fields | Modify existing metadata  |
| Delete existing images | `DELETE /imgs` | `id`            | None                  | Remove images from system |

<Note>
  Each image must have a **unique identifier** (`id`). The `src` field should contain the publicly accessible URL of the image.
</Note>

## Key Concepts

Understanding these concepts will help you choose the right configuration for your use case:

### Execution Modes

<CardGroup cols={2}>
  <Card title="Synchronous (Default)" icon="clock">
    **Best for**: Small operations (\< 10 uploads, \< 50 updates, \< 100 deletes)

    **Behavior**: Waits for completion before sending response
  </Card>

  <Card title="Asynchronous" icon="background">
    **Best for**: Large batch operations

    **Behavior**: Returns immediately with operation ID for tracking
  </Card>
</CardGroup>

### Processing Modes

| Mode                          | Behavior                    | When to Use                                      |
| ----------------------------- | --------------------------- | ------------------------------------------------ |
| **Strict** (default)          | Fails if ID conflicts occur | Production environments, data integrity critical |
| **Relaxed** (not implemented) | Handles conflicts flexibly  | Bulk imports, development                        |

<Tip>
  Start with **Strict + Synchronous** for small operations, then switch to **Strict + Asynchronous** for larger batches.
</Tip>

### Error Handling

| Strategy                     | Description                               | Best For                                    |
| ---------------------------- | ----------------------------------------- | ------------------------------------------- |
| **All or Nothing** (default) | Entire operation fails if any image fails | Critical operations requiring consistency   |
| **Subset** (not implemented) | Processes valid images, reports failures  | Large-scale imports, fault tolerance needed |

## Operation Monitoring

For asynchronous operations, you can track progress using the operations endpoints:

| Endpoint                  | Purpose                       | Response                                     |
| ------------------------- | ----------------------------- | -------------------------------------------- |
| `GET /ops`                | List all operations           | Array of operation objects                   |
| `GET /ops/{operation_id}` | Get specific operation status | Single operation object with detailed status |

### Operation Status Indicators

| Status                           | Description                                         |
| -------------------------------- | --------------------------------------------------- |
| `finished=false`, `success=null` | **Processing** - Operation is still running         |
| `finished=true`, `success=true`  | **Completed** - All items processed successfully    |
| `finished=true`, `success=false` | **Failed** - Operation aborted, check error details |

<Warning>
  If an operation fails (`success=false`), no database changes are made. Check the error message and retry with corrected data.
</Warning>

## Advanced Configuration

### Strict Mode Behavior

| Operation  | Strict Mode Behavior         | Impact                                     |
| ---------- | ---------------------------- | ------------------------------------------ |
| **Upload** | Error if `id` already exists | Prevents accidental overwrites             |
| **Update** | Error if `id` doesn't exist  | Ensures you're modifying existing data     |
| **Delete** | Ignores missing `id`         | Safe deletion of potentially removed items |

### Best Practices

<CardGroup cols={2}>
  <Card title="For Development" icon="code">
    * Use synchronous mode for testing
    * Start with small batches
    * Validate data structure first
  </Card>

  <Card title="For Production" icon="shield">
    * Use asynchronous for large operations
    * Monitor operation status
    * Implement retry logic for failures
  </Card>
</CardGroup>