Índice propio

Un índice propio es una lista de URLs que eliges tú, como páginas de productos, de relación con inversores, boletines oficiales o reseñas. Las leemos, las mantenemos al día y buscamos en ellas como buscamos en las noticias: una probabilidad calibrada en cada página, las mejores candidatas leídas antes de ordenarlas y respuestas tipadas en la misma llamada. Se busca con el mismo POST /v1/search, pasando index.

Crea un índice

curl https://api.typesearch.ai/v1/indexes \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Catalog" }'

Responde 201 con el índice:

{
  "id": "idx_8f3k2m9q",
  "object": "index",
  "name": "Catalog",
  "status": "active",
  "urls": { "total": 0, "ready": 0, "pending": 0, "failed": 0, "blocked": 0 },
  "sources": [],
  "last_read_at": null,
  "created_at": "2026-09-26T14:02:11Z",
  "updated_at": "2026-09-26T14:02:11Z"
}

GET /v1/indexes lista tus índices, con los limits de tu plan; GET /v1/indexes/{id} devuelve uno, y DELETE /v1/indexes/{id} lo borra con todo lo que tiene ({ "id": "idx_…", "deleted": true }). También puedes crear y administrar índices desde el panel, en Índices.

Agrega URLs, un sitemap o un feed

POST /v1/indexes/{id}/urls acepta cualquiera de los tres, en el mismo pedido:

curl https://api.typesearch.ai/v1/indexes/idx_8f3k2m9q/urls \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://shop.example/p/ridgeline-trail-4", "https://shop.example/p/canyon-grip-gtx"],
    "sitemap": "https://shop.example/sitemap.xml"
  }'

Responde 202 Accepted: las URLs quedan en la cola y se leen en el momento.

{
  "index": "idx_8f3k2m9q",
  "added": 2,
  "existing": 0,
  "invalid": [],
  "over_limit": 0,
  "total": 2,
  "sources": [
    {
      "url": "https://shop.example/sitemap.xml",
      "type": "sitemap",
      "status": "pending",
      "read_at": null,
      "urls": 0,
      "error": null
    }
  ],
  "limits": { "urls": 100, "urls_used": 2, "indexes": 3, "indexes_used": 1 },
  "warnings": []
}

• added y existing: las URLs nuevas, y las que ya estaban en tu índice.
• invalid: cada URL rechazada, con su reason; por ejemplo, porque no es una dirección http o https pública.
• over_limit: las URLs que no entraron en el límite de tu plan y no se agregaron. Ver límites y precio.
• total: las URLs que tiene tu índice ahora. sources: los sitemaps y feeds que sigue.
• warnings: avisos que no frenan el pedido, cada uno con un code y un message.

Para quitar URLs, envía DELETE /v1/indexes/{id}/urls con las urls a quitar, o con sources para quitar sitemaps o feeds por su URL. Responde cuántas se quitaron en removed.

Estados

Cada URL tiene un status:

GET /v1/indexes/{id}/urls las lista, filtradas por status si quieres, de a una página (limit, y cursor con el next_cursor de la página anterior; null en la última):

curl "https://api.typesearch.ai/v1/indexes/idx_8f3k2m9q/urls?status=failed&limit=50" \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY"

{
  "url": "https://shop.example/p/ridgeline-trail-4",
  "status": "ready",
  "title": "Ridgeline Trail 4 · trail running shoe",
  "description": "Grippy, light and made for long days on rough ground.",
  "data": { "price": 109, "currency": "USD", "availability": "InStock", "brand": "Ridgeline", "sku": "RT4-42" },
  "published_at": null,
  "read_at": "2026-09-26T09:14:02Z",
  "changed_at": "2026-09-24T09:10:40Z",
  "next_read_at": "2026-09-27T09:14:02Z",
  "error": null
}

data son los datos estructurados que declara la propia página (price, currency, availability, brand, sku…), o null si no declara ninguno.

El índice tiene su propio status: active, o paused cuando se acaba tu crédito. Un índice en pausa conserva sus URLs, pero no se vuelven a leer hasta que haya crédito.

Qué tan al día se mantiene

• Cada URL se vuelve a leer una vez por día. read_at dice cuándo se leyó por última vez, changed_at cuándo cambió su contenido y next_read_at cuándo se va a volver a leer.
• Los sitemaps y los feeds se revisan cada hora, y las URLs nuevas o actualizadas que traen se leen en el momento.
• Respetamos robots.txt en cada lectura.

Volver a leer está incluido en el precio.

Busca en él

Pasa index a POST /v1/search. Todo lo demás funciona como en cualquier búsqueda (modos, preguntas tipadas, tone, highlights, max_results, max_tokens), con dos diferencias: un pedido con index lleva una sola consulta, y no hay filtro de fechas salvo que indiques uno (days, published_after o published_before).

curl https://api.typesearch.ai/v1/search \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "trail running shoes under $120", "index": "idx_8f3k2m9q", "mode": "fast" }'

La respuesta es una respuesta de búsqueda común. Suma custom_index, y cada resultado dice found_in: "custom_index" y trae los data de la página:

{
  "object": "search",
  "mode": "fast",
  "custom_index": { "id": "idx_8f3k2m9q", "name": "Catalog" },
  "found": true,
  "results": [
    {
      "url": "https://shop.example/p/ridgeline-trail-4",
      "title": "Ridgeline Trail 4 · trail running shoe",
      "score": 0.96,
      "found_in": "custom_index",
      "data": { "price": 109, "currency": "USD", "availability": "InStock", "brand": "Ridgeline", "sku": "RT4-42" }
    }
  ]
}

Para poner tus páginas al lado de la cobertura de la prensa, envía la misma consulta dos veces: una con index y otra sin él.

Preguntas tipadas: precio, stock, «¿cambió?»

data te da lo que la página declara. Una pregunta tipada responde lo que no declara: si hay talla M, si cuesta menos que tu presupuesto, si cambió la política de devoluciones, si la empresa revisó sus proyecciones. Usa normal o deep cuando la respuesta está en la página y no en su título: leen las mejores candidatas antes de ordenarlas.

curl https://api.typesearch.ai/v1/search \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Alpine rain jacket in size M",
    "index": "idx_8f3k2m9q",
    "mode": "normal",
    "questions": {
      "in_stock": { "type": "boolean", "instructions": "Is size M in stock?" },
      "on_sale": { "type": "boolean", "instructions": "Is it discounted from its regular price?" }
    }
  }'

{
  "basis": "article",
  "values": {
    "in_stock": { "type": "boolean", "probability": 0.97 },
    "on_sale": { "type": "boolean", "probability": 0.08 }
  }
}

Como en cualquier búsqueda, una probabilidad entre 0,35 y 0,65 quiere decir sin decidir, y basis dice si la respuesta salió de la página o sólo de su título.

Límites y precio

Las URLs que pasan tu límite vuelven en over_limit y no se agregan. limits, en GET /v1/indexes y en cada POST /v1/indexes/{id}/urls, dice cuántas usas; null quiere decir sin límite. Más URLs vienen con el plan mensual de créditos.

Un índice cuesta $2,00 cada 1.000 URLs por mes, cobrado por día y prorrateado del mismo crédito prepago: un índice lleno de pago por uso, con 100 URLs, cuesta $0,20 por mes, y 10.000 URLs cuestan $20. Volver a leer está incluido. Las búsquedas en él cuestan lo mismo que cualquier búsqueda de ese modo: $1,00 cada 1.000 en ultra, $1,40 en fast, $2,20 en normal y $5,60 en deep. Ver Costos y caché.

Qué leemos, y qué no

• Sólo URLs públicas. Páginas que cualquiera puede abrir por http o https: sin inicios de sesión, cookies ni muros de pago. Las direcciones privadas y de redes internas se rechazan, y vuelven en invalid.
• La misma puerta de cumplimiento que el índice de noticias. robots.txt, las señales de exclusión de IA y las exclusiones de los medios se aplican a cada URL que agregas. Una página que dice que no vuelve como blocked, y no la leemos.
• Sólo tuyo. Un índice y lo que leemos para él son de tu organización: ningún otro cliente puede buscar en él.
• Nunca para entrenar. Tus URLs, las páginas que leemos para ellas y tus consultas nunca se usan para entrenar modelos.

Desde el servidor MCP

El search_news del servidor MCP acepta un index opcional: pasa tu idx_… y busca en tu índice en lugar del índice de noticias, con la misma key y los mismos precios. Así tu agente revisa tu catálogo y las noticias con la misma herramienta:

{ "query": "Alpine rain jacket in size M", "index": "idx_8f3k2m9q", "mode": "fast" }