# Catalog API Documentation

Service catalog and discovery API that aggregates component information from all ML services.

## Base URL

```
{BASE_URL}
```

- **Docker (internal):** `http://didiAI-catalog-api:11000`
- **Via gateway:** `http://<host>:11000/catalog/`

## Authentication

No authentication required on direct access. When accessed via the gateway, Bearer token authentication is enforced by nginx.

---

## Endpoints

### Health Check

```
GET /health
```

**Response:**
```json
{
  "status": "ok"
}
```

---

### List Components

List all registered components with full metadata (resource info, models, functions).

```
GET /v1/components
```

**Response:**
```json
{
  "components": [
    {
      "component_id": "llm-inference",
      "base_url": "http://didiAI-llm-api:14011",
      "resource": { "name": "LLM Inference Gateway", "slug": "llm-inference", ... },
      "models": [...],
      "functions": [...]
    }
  ],
  "total": 4,
  "errors": null
}
```

---

### Get Component

Get metadata for a specific component by ID.

```
GET /v1/components/{component_id}
```

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `component_id` | string | Component ID (e.g., `llm-inference`, `audio-transcription`, `video-analysis`, `web-factcheck`) |

**Response:** Same structure as a single component from `/v1/components`.

**Error (404):**
```json
{
  "detail": "Component 'unknown' not found"
}
```

---

### List Models

List all available models across all components.

```
GET /v1/models
```

**Response:**
```json
{
  "models": [
    {
      "name": "Qwen3.5-35B-A3B",
      "slug": "qwen3.5",
      "provider": "vllm",
      "model_type": "llm",
      "component_id": "llm-inference",
      "component_name": "LLM Inference Gateway"
    }
  ],
  "total": 5
}
```

---

### List Functions

List all available functions/endpoints across all components.

```
GET /v1/functions
```

**Response:**
```json
{
  "functions": [
    {
      "name": "Chat Completions",
      "slug": "chat-completions",
      "method": "POST",
      "path": "/v1/chat/completions",
      "component_id": "llm-inference"
    }
  ],
  "total": 10
}
```

---

### System Status

Aggregated health status of all components.

```
GET /v1/status
```

**Response:**
```json
{
  "status": "healthy",
  "components": [
    {
      "component_id": "llm-inference",
      "url": "http://didiAI-llm-api:14011",
      "reachable": true,
      "healthy": true,
      "status_code": 200
    }
  ],
  "healthy_count": 4,
  "total_count": 4
}
```

**Status values:** `healthy` (all ok), `degraded` (some ok), `unhealthy` (none ok).

---

### Aggregated OpenAPI Spec

Combined OpenAPI 3.1.0 specification from all components.

```
GET /v1/openapi
```

**Response:** Full OpenAPI JSON spec with paths prefixed by `/{component_id}` and schemas prefixed by `{component_id}_`.

---

### Swagger UI

Interactive API documentation (Swagger UI) for the aggregated spec.

```
GET /v1/docs
```

---

### ReDoc

Alternative API documentation (ReDoc) for the aggregated spec.

```
GET /v1/redoc
```

---

### Component OpenAPI Spec

Raw OpenAPI spec for a single component.

```
GET /v1/openapi/component/{component_id}
```

---

## Error Responses

| Code | Description |
|------|-------------|
| 404 | Component not found |
| 500 | Internal error (component unreachable) |

## Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Accept` | No | `application/json` (default) |