conqueia-com Directorio API

openapi: 3.2.0
info:
  title: pública de ¿Con qué IA? Directorio API
  version: 1.0.0
  summary: Busca y lee los casos, skills, apps, herramientas, guías y novedades de IA del directorio conqueia.com.
  description: API de solo lectura, gratuita, sin clave y con CORS abierto. Sirve para que asistentes y agentes de IA consulten el directorio en español de casos reales de IA para negocios. Cita siempre la `url` de conqueia.com de cada ficha que uses.
servers:
- url: https://conqueia.com
  description: Producción
tags:
- name: Directorio
  description: Buscar fichas y leerlas enteras.
paths:
  /api/v1/buscar:
    get:
      operationId: buscarFichas
      tags:
      - Directorio
      summary: Buscar fichas del directorio
      description: 'Busca casos de uso, skills, apps, herramientas y guías por palabras. Ordena por relevancia: los aciertos en el título valen más. Devuelve título, resumen, tema, herramientas y la URL de cada ficha.'
      parameters:
      - name: q
        in: query
        required: false
        description: 'Qué buscas, en lenguaje natural o con palabras clave: «facturas», «atender clientes por WhatsApp», «Claude Code». No distingue mayúsculas ni acentos. Sin q se devuelven las fichas más recientes que pasen los filtros.'
        schema:
          type: string
          maxLength: 300
        example: facturas
      - name: tipo
        in: query
        required: false
        description: Limita a un tipo de ficha.
        schema:
          type: string
          enum:
          - caso
          - skill
          - app
          - herramienta
          - guia
      - name: tema
        in: query
        required: false
        description: 'Limita a un tema, por nombre o por slug: ventas, marketing-y-anuncios, atencion-al-cliente, contenido-y-redes, facturas-y-finanzas, operaciones, investigacion, e-commerce, programacion, vida-y-casa, dinero-personal, viajes, compras, juegos, ciencia-y-seguridad. Acepta también parte del nombre («marketing»).'
        schema:
          type: string
        example: ventas
      - name: con
        in: query
        required: false
        description: Limita a las fichas que usan una herramienta o agente concreto, por ejemplo «Claude», «ChatGPT» o «n8n».
        schema:
          type: string
        example: claude
      - name: limite
        in: query
        required: false
        description: Máximo de resultados. Por defecto 10, máximo 50.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      responses:
        '200':
          description: Fichas que encajan, de la más a la menos relevante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespuestaBusqueda'
        '400':
          description: Un parámetro no es válido (tipo o tema desconocido). La respuesta lista los valores válidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/ficha:
    get:
      operationId: verFicha
      tags:
      - Directorio
      summary: Leer una ficha entera
      description: 'Devuelve una ficha completa en JSON: todas sus secciones, el prompt, las fuentes, su URL en conqueia.com y la de su versión en texto (markdown). El tipo y el slug salen de la búsqueda.'
      parameters:
      - name: tipo
        in: query
        required: true
        description: Tipo de ficha. «novedad» sirve para las novedades con página propia.
        schema:
          type: string
          enum:
          - caso
          - skill
          - app
          - herramienta
          - guia
          - novedad
      - name: slug
        in: query
        required: true
        description: 'Identificador de la ficha: el final de su URL (conqueia.com/caso/<slug>).'
        schema:
          type: string
      responses:
        '200':
          description: La ficha entera.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ficha'
        '400':
          description: Faltan parámetros o el tipo no existe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No hay ninguna ficha con ese tipo y slug. La respuesta sugiere fichas parecidas en «quizas».
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Ficha:
      type: object
      description: Ficha entera.
      required:
      - tipo
      - slug
      - titulo
      - resumen
      - url
      - url_texto
      properties:
        tipo:
          type: string
          enum:
          - caso
          - skill
          - app
          - herramienta
          - guia
          - novedad
        slug:
          type: string
        titulo:
          type: string
        resumen:
          type: string
        tema:
          type: string
        herramientas:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
        url_texto:
          type: string
          format: uri
        url_externa:
          type: string
          format: uri
        origen:
          type: string
    RespuestaBusqueda:
      type: object
      required:
      - consulta
      - total
      - devueltos
      - resultados
      properties:
        consulta:
          type: string
        total:
          type: integer
        devueltos:
          type: integer
        resultados:
          type: array
          items:
            $ref: '#/components/schemas/Resultado'
        ayuda:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    Resultado:
      type: object
      description: Una ficha en una lista de resultados.
      required:
      - tipo
      - slug
      - titulo
      - resumen
      - tema
      - herramientas
      - url
      - url_texto
      - origen
      properties:
        tipo:
          type: string
          enum:
          - caso
          - skill
          - app
          - herramienta
          - guia
        slug:
          type: string
        titulo:
          type: string
        resumen:
          type: string
        tema:
          type: string
        herramientas:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
        url_texto:
          type: string
          format: uri
        origen:
          type:
          - string
          - 'null'
externalDocs:
  description: Cómo conectar tu IA al directorio (conector MCP, API y skill)
  url: https://conqueia.com/agentes