Búsqueda

Próxima versión — Zylon 1.58Esta documentación se publica antes del lanzamiento para que puedas preparar tus integraciones de API. La imagen de la versión todavía no está disponible. Para instalaciones con 1.57, consulta la documentación de 1.57.

Usa la API de búsqueda para consultar contenido visible para el miembro autenticado del espacio de trabajo. Puedes combinar filtros de texto, recurso, proyecto, tipo de artefacto y fecha de creación en una sola solicitud.

Requisitos previos

Envía un token de API cuyos permisos efectivos incluyan la búsqueda en Workspace.
Envía el slug de la organización en la cabecera x-org.
La búsqueda semántica de ArtifactContent requiere un gateway de PrivateGPT vinculado a la colección de la organización. Las búsquedas solo por palabras clave no usan el motor semántico.

Buscar contenido de Workspace

Busca con GET /api/v1/app/search.

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Query	`q`	Si	Texto de búsqueda. Los espacios iniciales y finales se eliminan antes de validar el rango configurado: de 3 a 80 caracteres de forma predeterminada.
Query	`types`	No	Tipos de resultado. Acepta valores separados por comas o repetidos: `Project`, `Artifact`, `Thread`, `Interaction` y `ArtifactContent`. Por defecto incluye todos los tipos.
Query	`type`	No	Alternativa a `types`. Solo se usa cuando `types` está ausente.
Query	`project_ids`	No	Lista de UUID de proyectos que se incluirán. Acepta valores separados por comas o repetidos y busca únicamente en proyectos que también sean visibles para quien realiza la llamada.
Query	`exclude_project_ids`	No	Lista de UUID de proyectos que se excluirán. Acepta valores separados por comas o repetidos. La exclusión prevalece cuando un ID aparece en ambos filtros de proyecto.
Query	`artifact_types`	No	Tipos de artefacto para resultados `Artifact` y `ArtifactContent`. Acepta valores separados por comas o repetidos.
Query	`start_date`	No	Límite inferior inclusivo de la fecha de creación, en milisegundos desde la época Unix.
Query	`end_date`	No	Límite superior inclusivo de la fecha de creación, en milisegundos desde la época Unix. No puede ser anterior a `start_date`.
Query	`limit`	No	Límite positivo aplicado por separado a cada tipo de resultado. El valor predeterminado es `30`.

Los parámetros de lista distinguen mayúsculas de minúsculas, eliminan espacios y duplicados, y admiten ambos formatos:

types=Artifact,ArtifactContent
types=Artifact&types=ArtifactContent

artifact_types acepta InlineText, Document, Folder, Summary, Composition, SmartDoc, Link, BulkQA, ReadAndExtract, SqlDatabase, McpServer, Integration, Analysis y Skill. El contenido que se puede buscar actualmente incluye artefactos de la familia de documentos, enlaces visibles a ellos y flujos de agentes. Otros tipos de artefacto válidos pueden no producir resultados de artefactos o contenido.

curl "https://{BASE_URL}/api/v1/app/search?q=support%20summary&types=Artifact,ArtifactContent&project_ids={projectID}&artifact_types=Document,InlineText&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Ejemplo de respuesta

[
  {
    "id": "0198cc5a-4411-7000-8000-000000000001",
    "type": "Artifact",
    "match": "Q1 Support Summary",
    "rank": 0.0241,
    "keyword_score": 0.76,
    "metadata": {
      "name": "Q1 Support Summary",
      "type": "Document",
      "project_id": "0198cc5a-4411-7000-8000-000000000010",
      "project_name": "Customer Insights"
    }
  },
  {
    "id": "0198cc5a-4411-7000-8000-000000000002",
    "type": "ArtifactContent",
    "match": "Billing issues drove a significant share of support cases.",
    "rank": 0.0014,
    "semantic_score": 0.84,
    "metadata": {
      "name": "Support Analysis",
      "type": "Document",
      "project_id": "0198cc5a-4411-7000-8000-000000000010",
      "project_name": "Customer Insights"
    }
  }
]

Comportamiento de los filtros

Si types y type están presentes, types tiene prioridad y type se ignora.
Si omites project_ids, la búsqueda incluye todos los proyectos visibles. Los ID válidos de proyectos no accesibles se excluyen sin devolver un error.
exclude_project_ids se aplica después de project_ids. Si no queda ningún proyecto, la respuesta es [].
Los límites de fecha usan la fecha de creación de cada entidad. En resultados de contenido semántico, usan la fecha de creación del artefacto.
El filtro de tipo de artefacto solo afecta a resultados Artifact y ArtifactContent.
La búsqueda solo devuelve proyectos visibles, hilos activos visibles y sus interacciones, y artefactos disponibles y listos para usar.

Campos de respuesta

Campo	Tipo	Descripción
`id`	string	Identificador del resultado. Un resultado creado a partir de un enlace usa el ID del enlace.
`type`	string	`Project`, `Artifact`, `Thread`, `Interaction` o `ArtifactContent`.
`match`	string	Nombre o fragmento de contenido coincidente. En los fragmentos semánticos se elimina el formato Markdown.
`rank`	number	Puntuación combinada y ponderada usada para ordenar la respuesta. Siempre está presente.
`keyword_score`	number, opcional	Puntuación original de búsqueda por palabras clave. Se omite en resultados solo semánticos.
`semantic_score`	number, opcional	Puntuación original de búsqueda semántica. Se omite en resultados solo por palabras clave.
`metadata`	object	Detalles específicos del tipo de resultado.

Cómo interpretar las puntuaciones

rank combina la puntuación de origen, su posición en la lista de resultados léxicos o semánticos y una ponderación dinámica del origen. No es una probabilidad ni un porcentaje de confianza y no tiene un rango fijo. Usa el orden devuelto en vez de aplicar un umbral fijo.
keyword_score es la puntuación original de relevancia de búsqueda de texto completo de PostgreSQL. Los valores más altos se tratan como coincidencias léxicas más fuertes. Un nombre encontrado fuera del ranking de texto completo puede tener una puntuación de 0.
semantic_score es la puntuación original de recuperación semántica para el fragmento de contenido seleccionado. No es una confianza normalizada.
Compara puntuaciones originales solo entre resultados producidos por el mismo motor y para la misma consulta. No compares keyword_score con semantic_score ni puntuaciones de solicitudes distintas.
Los campos opcionales de puntuación se omiten del JSON en lugar de devolverse como null.

Los resultados se agrupan en este orden: Project, Artifact, Thread, Interaction y ArtifactContent. Dentro de cada grupo, los valores de rank más altos aparecen primero. Como limit se aplica por tipo de resultado, una respuesta con varios tipos puede contener más de limit elementos en total. Las entradas devueltas por ambos motores de búsqueda no se deduplican.

Metadatos por tipo de resultado

Tipo de resultado	Forma de `metadata`
`Project`	`entity`, que contiene `id`, `name`, `goal`, `default_member_role`, `default_role_enabled`, `visibility`, `member_count`, `members`, `project_context`, `use_citations`, `use_system_prompt` e `is_pinned`. Cada miembro contiene `id`, `role`, `account` e `is_project_member`.
`Artifact`	`name`, `type`, `project_id` y `project_name`. Los campos del proyecto pueden ser `null`.
`ArtifactContent`	`name`, `type`, `project_id` y `project_name`. Un resultado de enlace conserva la identidad del enlace y los metadatos del proyecto de destino, mientras que `type` identifica el tipo del artefacto original.
`Thread`	`name`, `project_id` y `project_name`.
`Interaction`	`content`, `thread_id`, `project_id`, `project_name` y `thread_name`.

Errores y casos límite

400: falta q o está vacío; consulta fuera del rango configurado; valores de lista vacíos o no válidos; UUID de proyecto no válido; fecha o límite no válidos; start_date posterior a end_date; limit menor que 1; o falta el contexto de organización.
401: autenticación ausente o no válida.
403: el token o la cuenta no tienen permiso de búsqueda en Workspace.
500: el despliegue no tiene idiomas de búsqueda configurados.
Una búsqueda válida sin coincidencias visibles devuelve [].

Primeros pasos

Construye con Zylon

Coding Agents

Requisitos previos

Buscar contenido de Workspace

Comportamiento de los filtros

Campos de respuesta

Cómo interpretar las puntuaciones

Metadatos por tipo de resultado

Errores y casos límite

​Requisitos previos

​Buscar contenido de Workspace

​Comportamiento de los filtros

​Campos de respuesta

​Cómo interpretar las puntuaciones

​Metadatos por tipo de resultado

​Errores y casos límite

Requisitos previos

Buscar contenido de Workspace

Comportamiento de los filtros

Campos de respuesta

Cómo interpretar las puntuaciones

Metadatos por tipo de resultado

Errores y casos límite