docs/api.md

# REST API Reference & Endpoints

The Object Intelligence Platform exposes FastAPI REST endpoints alongside the Gradio UI.

---

## Endpoints

### 1. `POST /api/detect`
Run multi-pipeline detection on an uploaded image file.

**Form Data:**
- `file`: Image file (JPG/PNG)
- `mode`: `combined` | `known` | `open_vocabulary` | `specific`
- `lock_mode`: `true` | `false`
- `lock_target`: string (optional)
- `open_vocab_prompts`: comma-separated string (optional)
- `confidence`: float (default `0.45`)

**Response:**
```json
{
  "status": "success",
  "mode": "combined",
  "lock_mode": true,
  "lock_target": "My Cup",
  "detection_count": 1,
  "detections": [
    {
      "bbox": [120, 85, 340, 410],
      "label": "My Cup",
      "category": "cup",
      "confidence": 0.94,
      "type": "specific",
      "source": "embedding"
    }
  ]
}
```

---

### 2. `GET /api/objects`
List all user-taught specific objects stored in the database.

---

### 3. `POST /api/objects`
Teach a new specific object with reference images.

---

### 4. `DELETE /api/objects/{object_id}`
Delete a taught specific object and its associated vectors.

---

### 5. `GET /api/downloads/export-db`
Download a ZIP archive containing the complete custom object database (`objects.db`) and reference image manifest.

---

### 6. `GET /api/health`
Health check status endpoint. Returns model load statuses and system state.