AI Directories

Desarrolladores

Abrir en Claude

API y MCP

Catálogo oficial de AI Directories: busca herramientas de IA y directorios de envío desde curl o un agente. Gratuito, documentado y mejor que hacer scraping.

RESTGET · Bearer aid_

www.aidirectori.es/api/v1

MCPHTTP fluido

api/mcp

OpenAPIespecificación de máquina

openapi.json

Busca en el catálogo de AI Directories, consulta un listado y explora directorios de envío, desde un agente o desde curl. REST y MCP comparten el mismo backend. Scrapers de terceros envuelven nuestras páginas públicas y cobran por un volcado de datos. Esta es la fuente oficial.

Ejemplo: GET /tools/transclipper

curl -s "https://www.aidirectori.es/api/v1/tools/transclipper" \
  -H "Authorization: Bearer aid_your_api_key"

{
  "success": true,
  "data": {
    "id": "69b81f3e40816562014e004a",
    "slug": "transclipper",
    "name": "TransClipper",
    "url": "https://www.aidirectori.es/ai-tools/transclipper",
    "website": "https://transclipper.ai",
    "tagline": "Steal the Blueprint Behind Any Viral Video",
    "description": "TransClipper is a powerful AI-driven tool designed for efficient content clipping and transcription.",
    "category": { "slug": "video", "name": "Video" },
    "tags": [
      { "slug": "ai", "name": "AI" },
      { "slug": "content-creation", "name": "Content Creation" }
    ],
    "pricing": "FREE",
    "rating": 4,
    "opens": 4030,
    "featured": true,
    "icon": "https://cdn.aidirectori.es/icons/1784893027853-vpj1hwsqkq.png"
  }
}

Lo que puedes hacer

• Buscar herramientas de IA por palabra clave, categoría, etiqueta o precio
• Obtener una herramienta por slug (listado público completo)
• Listar categorías y etiquetas
• Buscar directorios de envío (DR, costo, insignia)
• Obtener el perfil de un directorio con tu clave aid_

Lo que no puedes hacer

• Leer correos de fundadores o análisis privados
• Hacer scraping del sitio HTML o suplantar a un rastreador
• Republicar el catálogo como un directorio competidor
• Llamar a las API de escritura de socios sin una clave emitida

Por qué existe esto

La gente estaba haciendo scraping de aidirectori.es y vendiendo la exportación. La API oficial es gratuita para productos, investigación y agentes, con atribución, límites de tasa y una licencia: no puedes republicar el catálogo completo como un directorio competidor o un scraping de pago.

Úsalo en un agente

Cursor: .cursor/mcp.json o ~/.cursor/mcp.json. Sin espacio después de Authorization:: mcp-remote divide por espacios en blanco. Consulta Instalar MCP.

{
  "mcpServers": {
    "aidirectories": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://www.aidirectori.es/api/mcp",
        "--header", "Authorization:Bearer aid_your_real_key"
      ]
    }
  }
}

También legible por máquina

• /llms.txt: resumen del sitio para agentes
• /sitemap.xml
• 60 req/min · 400/hora por IP

Empezar / Inicio rápido

Inicio rápido

Crea una clave aid_, luego busca herramientas, obtén un listado y busca directorios.

Crea una clave en el panel de desarrollador y luego copia estas.

1. Buscar herramientas de IA

curl -s "https://www.aidirectori.es/api/v1/tools?q=image&limit=5" \
  -H "Authorization: Bearer aid_your_api_key"

2. Obtener un listado

curl -s "https://www.aidirectori.es/api/v1/tools/transclipper" \
  -H "Authorization: Bearer aid_your_api_key"

3. Buscar directorios

curl -s "https://www.aidirectori.es/api/v1/directories?q=ai&limit=5" \
  -H "Authorization: Bearer aid_your_api_key"

Las mismas operaciones vía MCP: añade el servidor con el mismo token Bearer y luego llama a search_tools, get_tool y search_directories. Consulta Instalación de MCP.

Empezar / Autenticación

Autenticación

Token Bearer mediante clave de API. Genera claves desde tu panel de desarrollador. Estándar 10/min, premium 60/min.

Autenticación

Token Bearer mediante clave de API. Genera claves desde tu panel de desarrollador.

Límites de tasa

Las claves estándar obtienen 10 solicitudes por minuto. Las claves premium obtienen 60. Mejora desde tu panel de desarrollador. Los encabezados de límite de tasa están en cada respuesta.

URL base

https://www.aidirectori.es/api/v1

1. 1 Obtén tu clave de API

   Ve al panel de desarrollador y crea una clave de API. Las claves comienzan con aid_. Guárdala de forma segura: no podrás volver a ver la clave completa. Se requiere uso aceptable Crear una clave requiere aceptar la Política de uso aceptable de la API. Clonar negocios, reconstruir AI Directories, republicación masiva, páginas SEO públicas no autorizadas, targeting abusivo, compartir credenciales y evadir controles de acceso están prohibidos y pueden resultar en una prohibición permanente de la plataforma.

2. 2 Haz tu primera solicitud

   Pasa tu clave como token Bearer en el encabezado Authorization. X-API-Key también se acepta, en cada endpoint. Ambos son intercambiables: lo que una clave puede alcanzar depende de la clave, no del encabezado en el que llega. Una clave de panel aid_ aún obtiene 403 en los endpoints de socios cuando se envía como X-API-Key; si ves 403, necesitas una clave diferente, no un encabezado diferente.

   curl -s "https://www.aidirectori.es/api/v1/tools?q=ai&limit=5" \
     -H "Authorization: Bearer aid_your_api_key"
   

3. 3 Analiza la respuesta

   Las lecturas exitosas devuelven { success: true, data }. Los endpoints de listas también incluyen pagination: sus campos y las reglas de limitación valen la pena leerlos antes de escribir un bucle de paginación. Observa X-RateLimit-Remaining.

   {
     "success": true,
     "data": [
       {
         "slug": "transclipper",
         "name": "TransClipper",
         "website": "https://transclipper.ai"
       }
     ]
   }
   

Claves de socios

Los socios de directorios que nos envían herramientas para el servicio de envío aún usan una clave emitida para POST /submit-ai-tool, estado, webhooks y soporte. Esas claves también funcionan para lecturas del catálogo. Consulta ¿Tienes un directorio?.

MCP / Instalación

Instalar MCP

MCP HTTP fluido alojado: envía la misma clave Bearer que en REST.

El servidor habla el Protocolo de Contexto de Modelo sobre HTTP fluido. Está alojado. Cada herramienta envuelve las mismas funciones que la API REST. Envía Authorization: Bearer aid_… desde tu panel de desarrollador.

https://www.aidirectori.es/api/mcp

Claude Code

claude mcp add --transport http aidirectories https://www.aidirectori.es/api/mcp \
  --header "Authorization: Bearer aid_your_api_key"

Cursor / Claude Desktop

Ámbito del proyecto: .cursor/mcp.json. Global: ~/.cursor/mcp.json. Claude Desktop: claude_desktop_config.json (solo stdio: este mismo bloque).

{
  "mcpServers": {
    "aidirectories": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://www.aidirectori.es/api/mcp",
        "--header", "Authorization:Bearer aid_your_real_key"
      ]
    }
  }
}

Sin espacio después de Authorization:: mcp-remote divide los argumentos por espacios en blanco, por lo que "Authorization: Bearer …" rompe el encabezado. Reinicia el cliente por completo después de editar el archivo.

Después de añadir el servidor, pide al agente que liste las herramientas. Deberías ver search_tools, get_top_tools, get_tool, list_categories, list_tags, search_directories, get_directory y list_directory_categories.

Verificar

curl -s https://www.aidirectori.es/api/mcp -X POST \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

MCP / Herramientas

Herramientas MCP

Cada herramienta MCP es un envoltorio ligero sobre el catálogo REST.

La autenticación es la misma clave Bearer aid_ que en REST.

Herramienta	REST	Entrada
search_tools	GET /tools	q, categoría, etiqueta, precio, destacado, página, límite
get_top_tools	GET /tools/top	límite, categoría
get_tool	GET /tools/{slug}	slug
list_categories	GET /categories	q, límite
list_tags	GET /tags	q, límite
search_directories	GET /directories	q, categoría, costo, destacado, página, límite
get_directory	GET /directories/{slug}	slug
list_directory_categories	GET /directory-categories	—

Las notas completas de campos están en Herramientas de IA y Directorios.

API REST / Descripción general

API REST

HTTP simple para scripts, CI e integraciones de socios. El servidor MCP llama a estas mismas rutas, por lo que un resultado nunca depende del transporte que lo solicitó.

Operación	Método	Ruta	Autenticación	Entrada
search_tools Búsqueda por palabra clave con filtros opcionales de categoría, etiqueta, precio y destacado.	GET	/tools	Bearer	q, categoría, etiqueta, precio, destacado, incluirAdultos, página, límite
get_top_tools Top N listados por aperturas: no se requiere palabra clave.	GET	/tools/top	Bearer	límite, categoría, incluirAdultos
list_categories Categorías de herramientas de IA con recuentos de herramientas: úsalo antes de filtrar la búsqueda.	GET	/categories	Bearer	q, límite
list_tags Etiquetas de herramientas de IA con recuentos de herramientas.	GET	/tags	Bearer	q, límite
get_tool El listado público completo de una herramienta de IA.	GET	/tools/{slug}	Bearer	slug
search_directories Busca directorios de envío por nombre, categoría o costo.	GET	/directories	Bearer	q, categoría, costo, destacado, página, límite
get_directory El perfil público completo de un directorio.	GET	/directories/{slug}	Bearer	slug
list_directory_categories Etiquetas de categorías de directorios para descubrir filtros.	GET	/directory-categories	Bearer	—
submit_ai_tool Crea un listado de herramienta de IA (y opcionalmente encola envíos a directorios).	POST	/submit-ai-tool	X-API-Key	nombre, sitio web, eslogan, descripción, categoría, precio, nombre del fundador, correo del fundador, etiquetas, tipo de pago, …
get_tool_status Consulta el progreso del envío a directorios de una herramienta que tu clave envió.	GET	/ai-tools/status	X-API-Key	id | slug | sitio web

El descubrimiento está en GET / y el documento OpenAPI en GET /openapi.json. Las notas de campos para respuestas del catálogo están en Herramientas de IA y Directorios.

Envoltorio, paginación y límites

Cada respuesta usa el mismo envoltorio. data es un array en búsquedas y un objeto en consultas de un solo elemento. Comprueba success antes de leer data.

{ "success": true, "data": [], "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 } }

{ "success": false, "error": "Invalid or revoked API key." }

GET /tools y GET /directories devuelven un objeto pagination. Los endpoints de taxonomía (/categories, /tags, /directory-categories) devuelven la lista completa y ninguna clave pagination.

página	La página que obtuviste, basada en 1
límite	Elementos por página realmente aplicados
total	Elementos coincidentes en todas las páginas
páginas	ceil(total / límite), o 0 si no hay coincidencias

Un límite sobredimensionado se recorta, no se rechaza. Si pides más que el máximo, obtienes el máximo, con un 200: ningún error te avisa de que ocurrió. /tools y /directories tienen un valor predeterminado de 20 y un tope de 100; /categories y /tags tienen un tope de 500. Un limit ausente, cero, negativo o no numérico vuelve al valor predeterminado, y page tiene un mínimo de 1. Así que lee pagination.limit de la respuesta en lugar de asumir que obtuviste el tamaño de página que pediste: esa suposición es lo que convierte un bucle de paginación en uno infinito.

page=1
while :; do
  body=$(curl -s "https://www.aidirectori.es/api/v1/tools?limit=100&page=$page" \
    -H "Authorization: Bearer $AID_KEY")
  echo "$body" | jq -e '.success' >/dev/null || { echo "$body"; break; }
  echo "$body" | jq -c '.data[]'
  pages=$(echo "$body" | jq '.pagination.pages')
  [ "$page" -ge "$pages" ] && break
  page=$((page + 1))
  sleep 6   # stay under 10 req/min on a standard key
done

Herramientas de IA

Explora, busca y filtra el catálogo en vivo, u obtén un listado por slug. Se asigna a MCP search_tools, get_top_tools, get_tool, list_categories y list_tags.

list_categories

Categorías de herramientas de IA con recuentos de herramientas: úsalo antes de filtrar la búsqueda.

REST	GET /categories
MCP	tools/call → list_categories
Autenticación	Bearer
Entrada	q, límite

curl -s "https://www.aidirectori.es/api/v1/categories" \
  -H "Authorization: Bearer aid_your_api_key"

get_top_tools

Top N listados por aperturas: no se requiere palabra clave.

REST	GET /tools/top
MCP	tools/call → get_top_tools
Autenticación	Bearer
Entrada	límite, categoría, incluirAdultos

curl -s "https://www.aidirectori.es/api/v1/tools/top?limit=10&category=image" \
  -H "Authorization: Bearer aid_your_api_key"

search_tools

Búsqueda por palabra clave con filtros opcionales de categoría, etiqueta, precio y destacado.

REST	GET /tools
MCP	tools/call → search_tools
Autenticación	Bearer
Entrada	q, categoría, etiqueta, precio, destacado, incluirAdultos, página, límite

curl -s "https://www.aidirectori.es/api/v1/tools?q=ai&limit=5" \
  -H "Authorization: Bearer aid_your_api_key"

get_tool

El listado público completo de una herramienta de IA.

REST	GET /tools/{slug}
MCP	tools/call → get_tool
Autenticación	Bearer
Entrada	slug

curl -s "https://www.aidirectori.es/api/v1/tools/transclipper" \
  -H "Authorization: Bearer aid_your_api_key"

list_tags

Etiquetas de herramientas de IA con recuentos de herramientas.

REST	GET /tags
MCP	tools/call → list_tags
Autenticación	Bearer
Entrada	q, límite

curl -s "https://www.aidirectori.es/api/v1/tags" \
  -H "Authorization: Bearer aid_your_api_key"

Directorios

El catálogo de directorios de envío: Domain Rating, costo, insignia y categorías. Se asigna a MCP search_directories, get_directory y list_directory_categories.

search_directories

Busca directorios de envío por nombre, categoría o costo.

REST	GET /directories
MCP	tools/call → search_directories
Autenticación	Bearer
Entrada	q, categoría, costo, destacado, página, límite

curl -s "https://www.aidirectori.es/api/v1/directories?cost=Free&limit=10" \
  -H "Authorization: Bearer aid_your_api_key"

get_directory

El perfil público completo de un directorio.

REST	GET /directories/{slug}
MCP	tools/call → get_directory
Autenticación	Bearer
Entrada	slug

curl -s "https://www.aidirectori.es/api/v1/directories/theres-an-ai-for-that" \
  -H "Authorization: Bearer aid_your_api_key"

list_directory_categories

Etiquetas de categorías de directorios para descubrir filtros.

REST	GET /directory-categories
MCP	tools/call → list_directory_categories
Autenticación	Bearer
Entrada	—

curl -s "https://www.aidirectori.es/api/v1/directory-categories" \
  -H "Authorization: Bearer aid_your_api_key"

Socios

Los endpoints de escritura y estado necesitan un X-API-Key emitido. Mantenlo en tu servidor. MCP no llama a estos. Las listas completas de campos están en Envío y socios.

submit_ai_tool

Crea un listado de herramienta de IA (y opcionalmente encola envíos a directorios).

REST	POST /submit-ai-tool
MCP	—
Auth	X-API-Key
Input	name, website, tagline, description, category, pricing, founderName, founderEmail, tags, paymentType, …

curl -s -X POST "https://www.aidirectori.es/api/v1/submit-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Tool",
    "website": "https://mytool.com",
    "tagline": "One-line pitch",
    "description": "What the product does.",
    "category": "productivity",
    "pricing": "FREE",
    "paymentType": "pro",
    "founderName": "Jane Founder",
    "founderEmail": "jane@mytool.com",
    "tags": ["ai", "productivity"],
    "icon": "https://mytool.com/icon.png",
    "frame": "https://mytool.com/screenshot.png",
    "screenshots": ["https://mytool.com/gallery-1.png"]
  }'

get_tool_status

Consulta el progreso del envío al directorio de una herramienta que tu clave haya enviado.

REST	GET /ai-tools/status
MCP	—
Auth	X-API-Key
Input	id | slug | website

curl -s "https://www.aidirectori.es/api/v1/ai-tools/status?slug=my-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY"

REST API / Herramientas de IA

Herramientas de IA

Explora, busca y obtén listados de herramientas de IA publicadas.

search_tools

Búsqueda por palabras clave con filtros de categoría, etiqueta, precio y destacados.

REST	GET /tools
MCP	search_tools
Auth	Bearer aid_
Input	q, category, tag, pricing (FREE | FREEMIUM | PAID), featured, includeAdult, page, limit (máx. 100)

curl -s "https://www.aidirectori.es/api/v1/tools?q=transclipper&limit=5" \
  -H "Authorization: Bearer aid_your_api_key"

Cada elemento incluye nombre, slug, URL del listado, sitio web, eslogan, descripción, categoría, etiquetas, precio, calificación, aperturas, icono y marcas de tiempo. Sin correo del fundador.

Los listados para adultos están excluidos por defecto. search_tools y get_top_tools retienen los listados para adultos a menos que los solicites.

La exclusión es por categoría y etiqueta, porque las herramientas para adultos suelen clasificarse en una categoría general — image, writing, video — mientras se etiquetan con precisión. Así, category=image devuelve herramientas de imagen sin las aplicaciones de desnudado.

Tres formas de optar: includeAdult=true, category=nsfw, o nombrar una etiqueta para adultos como tag=ai-undressing. Nada está oculto o inaccesible — simplemente no es lo que obtienes cuando no lo pediste.

get_top_tools

Herramientas publicadas más abiertas. Slug de categoría opcional.

curl -s "https://www.aidirectori.es/api/v1/tools/top?limit=10&category=image" \
  -H "Authorization: Bearer aid_your_api_key"

get_tool

Listado público completo: capturas de pantalla, preguntas frecuentes, redes sociales, características.

curl -s "https://www.aidirectori.es/api/v1/tools/transclipper" \
  -H "Authorization: Bearer aid_your_api_key"

list_categories / list_tags

curl -s "https://www.aidirectori.es/api/v1/categories" -H "Authorization: Bearer aid_your_api_key"
curl -s "https://www.aidirectori.es/api/v1/tags?q=photo" -H "Authorization: Bearer aid_your_api_key"

Las categorías devuelven slug, name, description, icon, toolsCount. Las etiquetas devuelven slug, name, toolsCount. Ninguna está paginada — obtienes la lista completa, así que guárdala en caché y filtra localmente.

Campos de herramienta

Devueltos por /tools, /tools/top y /tools/{slug} por igual:

Campo	Tipo	Notas
id	string	Identificador estable
slug	string	Úsalo para /tools/{slug}
name, tagline, description	string
url	string	El listado en aidirectori.es
website	string	El sitio propio del producto
category	object	{ slug, name }, o null
tags	array	[{ slug, name }]
pricing	string	FREE | FREEMIUM | PAID
rating	number	0 cuando no está calificado
opens	number	Clics; lo que /tools/top ordena
featured	boolean
icon, frame	string	URLs de imagen, anulables
founderName, location	string	Anulables. Sin correo del fundador, nunca
domainRating	number	Anulable
isForSale, askingPrice	boolean, number	Listados marcados para adquisición
discountCode, affiliate	string, boolean
createdAt, updatedAt	string	ISO 8601, anulable

GET /tools/{slug} añade screenshots (array de URLs), video, socials, faqs, features, y affiliateLink. Esos seis están solo en el endpoint de herramienta única — no los esperes de una búsqueda.

Cualquier campo puede ser null cuando un listado no lo ha completado. Programa defensivamente.

REST API / Directorios

Directorios

La otra mitad del catálogo — directorios de envío para startups y SaaS, con DR y precios.

Los rastreadores suelen perderse esto. Es la lista a la que realmente enviamos productos.

search_directories

REST	GET /directories
MCP	search_directories
Auth	Bearer aid_
Input	q, category, cost (Free | Paid | Freemium), featured, page, limit

curl -s "https://www.aidirectori.es/api/v1/directories?cost=Free&limit=10" \
  -H "Authorization: Bearer aid_your_api_key"

Los campos incluyen nombre, URL del listado, sitio web, Domain Rating, visitas mensuales, tipo de enlace, requisito de insignia, precio mínimo y categorías.

get_directory

Añade descripción, preguntas frecuentes, enlace de envío y texto de oferta.

curl -s "https://www.aidirectori.es/api/v1/directories/theres-an-ai-for-that" \
  -H "Authorization: Bearer aid_your_api_key"

list_directory_categories

curl -s "https://www.aidirectori.es/api/v1/directory-categories" \
  -H "Authorization: Bearer aid_your_api_key"

Devuelve solo slug y name. No está paginado. Estos son los valores que ?category= acepta — léelos en lugar de adivinar.

Campos de directorio

Campo	Tipo	Notas
id, slug, name	string
url	string	El perfil en aidirectori.es
website	string	El sitio propio del directorio
icon	string	Anulable
cost	string	Free | Paid | Freemium
type	string	Tipo de enlace
domainRating	number	Anulable — el número por el que la mayoría ordena
monthlyVisits	number	Anulable
requiresBadge	boolean	Si exigen una insignia de enlace de retroceso
minimumPrice	number	0 cuando es gratis
submissionExperience	string	Anulable
featured	boolean
categories	array	[{ slug, name }]
smallDescription	string	Anulable
createdAt, updatedAt	string	ISO 8601

GET /directories/{slug} añade fullDescription, features, useCases, faq, deal ({ text, code } o null), frame, y socials.

Nota los dos campos url: url es nuestra página de perfil, website es el directorio en sí. Las URLs de formularios de envío directo (submissionLink) no están en la API del catálogo ni en MCP — son parte del producto de lista de pago en el sitio y el panel.

Elegir objetivos de envío

curl -s "https://www.aidirectori.es/api/v1/directories?cost=Free&limit=100" \
  -H "Authorization: Bearer $AID_KEY" \
  | jq -r '.data
      | map(select(.requiresBadge == false and .domainRating != null))
      | sort_by(-.domainRating)
      | .[]
      | [.domainRating, .name, .website] | @tsv'

Gratis, sin insignia requerida, dominios más fuertes primero.

REST API / Envío y socios

Envío y socios

Endpoints con clave de API para enviar herramientas, consultar estado, webhooks y soporte.

Estos no son anónimos. Emitimos una clave por socio. MCP no los llama.

Enviar una herramienta

POST https://www.aidirectori.es/api/v1/submit-ai-tool

Crea un listado. Envía paymentType para poner en cola los envíos al directorio para ese paquete. Omítelo y la herramienta se crea como en espera para que el paquete se pueda configurar más tarde en el panel de administración.

Requeridos

9

Si falta cualquiera de estos, devuelve 400.

CampoTipoNotas

• name string Máximo 100 caracteres.
• website url URL pública del producto.
• tagline string Máximo 200 caracteres.
• description string Qué hace el producto.
• category string Slug o nombre. Lo mapeamos a una categoría existente.
• pricing enum FREE PAID FREEMIUM El precio propio del producto — no el paquete de directorio.
• founderName string Lo recopilas antes de hacer el POST.
• founderEmail email Lo recopilas. Nunca se devuelve en lecturas públicas del catálogo. No lo envíes desde un navegador.
• tags string[] Slugs o nombres.

Recomendados

5

La solicitud tiene éxito sin estos — generamos un slug, obtenemos icono/og:image y dejamos el paquete como en espera. Envíalos cuando los tengas.

CampoTipoNotas

• paymentType enum starter pro premium Paquete de directorio: 30+, 60+ o 100+ envíos. Envía esto si el cliente ya eligió un paquete. Omítelo solo si quieres que la herramienta se cree como en espera para que el administrador lo configure más tarde.
• slug string Slug de URL pública. Se genera desde el nombre (y se hace único) si se omite — envíalo cuando ya tengas un slug estable.
• icon url Logotipo cuadrado. Si se omite, obtenemos el favicon del sitio — envía el tuyo para un mejor listado.
• frame url Captura de pantalla principal. Si se omite, obtenemos og:image — envía una toma del producto cuando la tengas.
• screenshots url[] Imágenes de galería, reflejadas a Cloudflare. No requeridas; el marco cubre la imagen principal si esto está vacío.

Opcionales

11

Las imágenes en URLs públicas se reflejan a Cloudflare.

CampoTipoNotas

• video url YouTube o Vimeo.
• socials object Claves a URLs, p. ej. { "twitter": "https://x.com/…" }.
• features object Mapa de cadenas, p. ej. { "Templates": "50+" }. Se genera si se omite.
• faq array Si se omite, se extrae del sitio o se genera.
• affiliate string Texto del programa de afiliados.
• affiliateLink url
• discountCode string Código de promoción mostrado en el listado.
• location string Dónde tiene su sede la empresa.
• foundingDate string Fecha de fundación, formato libre.
• isCustomer boolean Si ya son clientes.
• isLaunched boolean Si el producto está en vivo.

curl -s -X POST "https://www.aidirectori.es/api/v1/submit-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Tool",
    "website": "https://mytool.com",
    "tagline": "One-line pitch",
    "description": "What the product does.",
    "category": "productivity",
    "pricing": "FREE",
    "paymentType": "pro",
    "founderName": "Jane Founder",
    "founderEmail": "jane@mytool.com",
    "tags": ["ai", "productivity"],
    "icon": "https://mytool.com/icon.png",
    "frame": "https://mytool.com/screenshot.png",
    "screenshots": ["https://mytool.com/gallery-1.png"]
  }'

Consultar estado del envío

GET https://www.aidirectori.es/api/v1/ai-tools/status — busca una herramienta que tu clave envió con exactamente uno de id, slug, o website. Las herramientas de otros clientes devuelven 404.

Úsalo en cualquier momento — no solo cuando se dispara un webhook. Consulta mientras summary.isComplete sea false, luego detente (o espera a Done). submissionState es IN_QUEUE, ASSIGNED, IN_PROGRESS, REVIEW, DONE, o null cuando no hay flujo de trabajo de directorio.

curl -s "https://www.aidirectori.es/api/v1/ai-tools/status?slug=my-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY"

Webhook

Enviamos JSON por POST a una URL HTTPS almacenada en tu cliente de API — no se envía en cada envío. Danos la URL cuando solicites; la almacenamos como webhookUrl y te enviamos un secreto de firma. Tanto las respuestas de directorio-Done como las de soporte llegan a ese mismo endpoint.

El evento de directorio se dispara cuando un administrador hace clic en Done en una herramienta que tu clave envió y webhookUrl está configurado. URL faltante: no enviamos nada. Tu endpoint caído o no-2xx: la herramienta aún se marca como Done. No reintentamos todavía — consulta el estado si necesitas un respaldo.

Eventos

2

Lee X-AI-Directories-Event antes de analizar el cuerpo.

CampoTipoNotas

• directory_submissions.completed Done El administrador marcó el trabajo de directorio como Done para una herramienta que tu clave envió. El payload es { event, occurredAt, tool, summary, submissions }.
• support.replied reply Una respuesta de soporte está lista (IA o humana). El payload es { event, occurredAt, conversation }. Solo si el soporte está habilitado.

Solicitud

Método	POST
Content-Type	application/json
Auth	Cabecera HMAC — no tu clave de API

Cabeceras

3

CampoTipoNotas

• X-AI-Directories-Event string Qué payload recibiste. Ramifica en esto — la misma URL recibe ambos eventos.
• X-AI-Directories-Signature string sha256=<hex> HMAC del cuerpo crudo con tu secreto de firma. Presente cuando emitimos un secreto.
• User-Agent string AI-Directories-Webhook/1.0

Verificar la firma

HMAC-SHA256 sobre el cuerpo de solicitud crudo con el secreto que te dimos. Compara el resumen hexadecimal con X-AI-Directories-Signature después de eliminar el prefijo sha256=. Usa una comparación segura en tiempo.

const crypto = require("crypto");

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = String(signatureHeader || "").replace(/^sha256=/, "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Payload

submissions solo incluye directorios a los que realmente enviamos. Cada fila puede incluir el listingUrl en vivo, captura de pantalla de prueba, domain rating y quién lo envió (ADMIN o OWNER). Devuelve 2xx para confirmar.

{
  "event": "directory_submissions.completed",
  "occurredAt": "2026-09-01T13:00:00.000Z",
  "tool": {
    "id": "64a1b2c3d4e5f6789012345",
    "name": "My AI Tool",
    "slug": "my-ai-tool",
    "website": "https://myaitool.com",
    "paymentStatus": "prolist",
    "paymentLabel": "Pro · 60+",
    "targetDirectoriesCount": 60
  },
  "summary": {
    "submittedCount": 62,
    "recordedSubmissions": 62,
    "notes": "All high-DR directories completed"
  },
  "submissions": [
    {
      "name": "There's An AI For That",
      "slug": "theres-an-ai-for-that",
      "url": "https://theresanaiforthat.com",
      "listingUrl": "https://theresanaiforthat.com/ai/my-ai-tool",
      "domainRating": 81,
      "isSubmitted": true,
      "submittedBy": "ADMIN",
      "submittedAt": "2026-09-01T12:00:00.000Z"
    }
  ]
}

Soporte al cliente

Reenvía una pregunta desde tu interfaz de producto; respondemos desde tu base de conocimiento cuando podemos, o un humano responde en nuestro panel. Desactivado por defecto — hasta que lo habilitemos, POST /support/ask devuelve 403. Mismo X-API-Key que el envío. MCP no puede llamar esto.

El modo predeterminado es híbrido: la IA responde cuando puede, de lo contrario la conversación permanece pending para un humano. Podemos configurar el cliente solo-humano (sin IA). Sin conocimiento del producto, las preguntas esperan a una persona.

Enviar una pregunta

POST https://www.aidirectori.es/api/v1/support/ask

Cuerpo

5 question es obligatorio. Reutiliza conversationId o externalId para continuar un hilo. Los clientes solo humanos pueden enviar metadata.peerPushMessageId para reintentos idempotentes.

FieldTypeNotes

• question string La pregunta del cliente. Máximo 4000 caracteres. message también se acepta.
• conversationId string Continúa un hilo que devolvimos anteriormente.
• externalId string Tu ticket o id de hilo. Reutilizarlo continúa la misma conversación.
• customer object { name, email, id } opcional para el cliente final — no el fundador de submit.
• metadata object JSON arbitrario almacenado en la conversación.

curl -s -X POST "https://www.aidirectori.es/api/v1/support/ask" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I cancel my subscription?",
    "externalId": "ticket-123",
    "customer": { "name": "Ada", "email": "ada@example.com" }
  }'

Híbrido/AI: 200 con status: "answered" significa que reply está listo (replySource es ai o human). pending significa hacer polling o esperar el webhook.

{
  "success": true,
  "data": {
    "id": "64a1b2c3d4e5f6789012345",
    "status": "answered",
    "externalId": "ticket-123",
    "reply": "You can cancel from Settings → Billing.",
    "replySource": "ai",
    "messages": [
      { "role": "customer", "content": "How do I cancel my subscription?" },
      { "role": "assistant", "content": "You can cancel from Settings → Billing.", "source": "ai" }
    ]
  }
}

Los clientes solo humanos reciben un sobre reducido — sin historial, customer, ni messages[]. message es null hasta que un humano responde, luego un único mensaje de agente.

{
  "success": true,
  "data": {
    "id": "64a1b2c3d4e5f6789012345",
    "externalId": "ticket-123",
    "status": "pending",
    "message": null
  }
}

Consultar una conversación

GET https://www.aidirectori.es/api/v1/support/conversations/:id — o listar con ?id=, ?externalId=, o ?status=pending. Intervalo sugerido mientras está pendiente: 5–15 segundos. Los resultados de listado híbrido omiten el array completo de messages; solo humanos devuelve la misma forma reducida que ask.

curl -s "https://www.aidirectori.es/api/v1/support/conversations/64a1b2c3d4e5f6789012345" \
  -H "X-API-Key: YOUR_API_KEY"

Webhook cuando una respuesta está lista

Si webhookUrl está configurado, hacemos POST a support.replied — mismo HMAC que directory Done. El payload híbrido/AI usa reply / replySource. Solo humanos usa un conversation.message singular con role: "agent" y source: "human".

{
  "event": "support.replied",
  "occurredAt": "2026-09-09T09:01:00.000Z",
  "conversation": {
    "id": "64a1b2c3d4e5f6789012345",
    "status": "answered",
    "externalId": "ticket-123",
    "reply": "You can cancel from Settings → Billing.",
    "replySource": "human"
  }
}

{
  "event": "support.replied",
  "occurredAt": "2026-09-11T12:00:00.000Z",
  "conversation": {
    "id": "64a1b2c3d4e5f6789012345",
    "externalId": "ticket-123",
    "status": "answered",
    "message": {
      "id": "...",
      "role": "agent",
      "source": "human",
      "content": "Thanks — here's how to cancel…",
      "createdAt": "2026-09-11T12:00:00.000Z"
    }
  }
}

Envía un correo a support@thedirectori.es para obtener una clave, URL de webhook, secreto de firma o acceso de soporte — o solicítalo desde ¿Tienes un directorio?.

Referencia / Límites de tasa

Límites de tasa

Las claves estándar obtienen 10 solicitudes por minuto. Las claves premium obtienen 60. Encabezados en cada respuesta.

Los límites son por clave de API, no por IP — y REST y MCP usan presupuestos separados, por lo que una ráfaga de agente no puede agotar tus scripts del lado del servidor.

Clave	REST / minuto	MCP / minuto
Estándar (aid_ desde el panel)	10	30
Premium (plan de API de Catálogo de pago, concesión de administrador o clave de socio emitida)	60	120

El presupuesto de MCP es el más grande porque los agentes se ramifican: una pregunta de un usuario se convierte rutinariamente en varias llamadas de herramienta en paralelo.

El handshake es gratuito

initialize, notifications/initialized, ping y tools/list no cuestan nada. Conectar un cliente, o reiniciarlo, no gasta tu cuota — solo tools/call lo hace. Un cuerpo de solicitud malformado tampoco se cobra.

Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. 429 también envía Retry-After.

Mejora desde tu panel de desarrollador ($9/mes). No te hagas pasar por rastreadores de motores de búsqueda o asistentes para volcar el catálogo.

¿Necesitas un límite más alto? Envía un correo a support@thedirectori.es.

Las claves de socio de submit/soporte tienen sus propios límites de escritura; usan el presupuesto de catálogo premium al leer.

Referencia / Errores

Errores

Forma de error JSON y códigos de estado HTTP.

{ "success": false, "error": "Tool not found." }

HTTP	Significado
400	Solicitud incorrecta
401	Clave de API faltante o inválida
403	Clave válida pero función no habilitada
404	Herramienta, directorio o conversación no encontrada
429	Límite de tasa
500 / 503	Problema de servidor o base de datos — reintentar

MCP usa errores JSON-RPC (-32601 método no encontrado, -32603 interno y payloads de herramienta isError).