# HST API

**Base URL:** https://tzrtech.org/api  
**Estado:** Implementado

---

## Endpoints

### Listar Tags

```
GET /tags
```

**Query params:**

| Param | Tipo | Descripción |
|-------|------|-------------|
| grupo | string | Filtrar por grupo (hst, spe, vsn, flg, vue) |
| activo | boolean | Solo activos |
| limit | integer | Límite de resultados |

**Response:**

```json
{
  "tags": [
    {
      "ref": "person",
      "h_maestro": "a1b2c3...",
      "grupo": "hst",
      "nombre_es": "Persona",
      "nombre_en": "Person",
      "imagen_url": "https://tzrtech.org/a1b2c3...png"
    }
  ],
  "total": 639
}
```

---

### Obtener Tag

```
GET /tags/{ref}
```

**Response:**

```json
{
  "ref": "person",
  "h_maestro": "a1b2c3...",
  "grupo": "hst",
  "nombre_es": "Persona",
  "nombre_en": "Person",
  "descripcion": "...",
  "imagen_url": "https://tzrtech.org/a1b2c3...png",
  "activo": true,
  "version": 1
}
```

---

### Buscar Tags

```
GET /tags/search?q={query}
```

**Response:**

```json
{
  "query": "person",
  "results": [
    { "ref": "person", "score": 1.0 },
    { "ref": "people", "score": 0.8 }
  ]
}
```

---

### Biblioteca de Usuario

```
GET /biblioteca
```

**Headers:**

```
Authorization: Bearer {token}
```

**Response:**

```json
{
  "user_id": 123,
  "tags": [
    {
      "ref": "mi_tag",
      "h_usuario": "def456...",
      "nombre": "Mi Tag Personal"
    }
  ]
}
```

---

### Crear Tag de Usuario

```
POST /biblioteca
```

**Body:**

```json
{
  "ref": "mi_tag",
  "nombre": "Mi Tag Personal",
  "metadata": {}
}
```

**Response:**

```json
{
  "ref": "mi_tag",
  "h_usuario": "def456...",
  "created": true
}
```

---

## Autenticación

| Endpoint | Auth |
|----------|------|
| GET /tags | Pública |
| GET /tags/{ref} | Pública |
| GET /tags/search | Pública |
| GET /biblioteca | Token requerido |
| POST /biblioteca | Token requerido |

---

## Rate Limits

| Tipo | Límite |
|------|--------|
| Público | 100 req/min |
| Autenticado | 1000 req/min |