> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Artefactos

> Artefactos de Workspace para documentos, flujos y conectores.

<Warning>
  **Próxima versión — Zylon 1.58**

  Esta 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](/es/v1.57/overview).
</Warning>

<Warning>
  Las URLs de artefactos, las codificaciones de contenido y los campos de respuesta cambian en 1.58. Consulta [Migración de API 1.57 → 1.58](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#rutas-de-artefactos) antes de actualizar tu integración.
</Warning>

Un artefacto es una pieza de información **o herramienta** que le entregas a Zylon para usarla como contexto en consultas y operaciones. La Workspace API agrupa los artefactos en **documentos**, **documentos IA** y **otros artefactos**.

## Requisitos previos

* Un token de API. Ver [Gestión de tokens de Workspace](/es/v1.58/developer-manual/get-started/token-management).
* El nombre de host de Zylon (sustituye `{BASE_URL}` en los ejemplos).

## Artefactos

| Categoría | Incluye | Cuándo usar |
| - | - | - |
| **Artefactos de documento** | Documentos, carpetas, enlaces | Guardar u organizar contenido en un proyecto. |
| **Documentos IA** | `Summary`, composición, extracción | Ejecutar flujos sobre artefactos para producir resultados. |
| **Otros artefactos** | Servidores MCP, bases de datos SQL, integraciones, skills | Conectar herramientas, fuentes externas o instrucciones reutilizables. |

### Campos de petición de artefacto

Usa `POST /api/v1/app/artifact` para crear cualquier tipo de artefacto. El cuerpo indica la organización o el proyecto propietario e incluye metadatos compartidos y un objeto `props` específico del tipo.

Cuando envías la cabecera `x-org`, omite `organization_id`: la organización se obtiene de la cabecera. Usa `project_id` para crear el artefacto dentro de un proyecto u omítelo para crear un artefacto de organización; esto último requiere el rol `AppAdmin` o superior. Sin `x-org`, los operadores y superadministradores deben enviar `organization_id`; si también envían `project_id`, este debe pertenecer a esa organización. Los artefactos `Link` siempre requieren `project_id`.

<Accordion title="Campos de petición de artefacto">
  | Campo | Tipo | Obligatorio | Descripción |
  | - | - | - | - |
  | `organization_id` | string | Condicional | Organización propietaria. Omítelo al usar `x-org`; sin esa cabecera, solo pueden enviarlo operadores y superadministradores. |
  | `project_id` | string \| null | No | Proyecto propietario. Omítelo o usa `null` para crear un artefacto de organización. Es obligatorio para `Link`. |
  | `type` | string | Sí | Tipo de artefacto. Los tipos expuestos incluyen `Document`, `Folder`, `Link`, `Integration`, `Skill`, `Summary`, `Composition`, `BulkQA`, `ReadAndExtract`, `Analysis`, `SmartDoc`, `SqlDatabase` y `McpServer`. |
  | `name` | string | Sí | Nombre visible del artefacto. |
  | `props` | object | Sí | Configuración específica del tipo. También se acepta el alias legado `config`. |
  | `source` | string | No | Fuente del artefacto. Los valores de producción son `User`, `SharePoint`, `GoogleDrive`, `Confluence`, `ConfluenceLocalLegacy`, `Claromentis`, `FileSystem`, `Assistant` y `System`. Por defecto es `User`. |
  | `description` | string | No | Descripción legible. |
  | `parent_id` | string | No | Artefacto padre para artefactos de árbol, como documentos, carpetas y enlaces. No lo uses para artefactos MCP o de base de datos. |
  | `integration_id` | string | No | ID de integración para artefactos respaldados por integraciones. También se acepta `integration_artifact_id`. |
  | `external_url` | string | No | URL externa para enlaces o artefactos respaldados por conectores. |
  | `content` | string | Condicional | Contenido codificado en Base64 al crear mediante JSON. Para crear correctamente un `Document` o `Skill`, envía este campo o `file_data` multipart. |
  | `keep_file_after_ingestion` | boolean | No | Indica si se conserva el archivo subido tras la ingesta. Por defecto es `true`. |
  | `interaction_id` | string | No | Interacción que produjo el artefacto, si aplica. |
  | `private_props` | object | No | Configuración privada para artefactos `Integration` respaldados por proveedores, MCP y SQL database. También se acepta el alias legado `private_config` al crear. |
  | `scopes` | object\[] | No | Alcances iniciales del artefacto. |
  | `scopes[].scope_type` | string | Sí | `organization` o `project`. |
  | `scopes[].scope_id` | string | Sí | ID de la organización o el proyecto indicado por `scope_type`. |
  | `scopes[].enabled` | boolean | No | Indica si el artefacto está visible en este alcance. Por defecto es `true` al crear un alcance. |
  | `scopes[].ws_auto_select` | boolean | No | Permite que Workspace seleccione automáticamente el artefacto en este alcance. Por defecto es `false` al crear un alcance. |
  | `scopes[].delete` | boolean | No | Elimina el alcance coincidente. Por defecto es `false`; se usa normalmente al actualizar o modificar alcances. |
  | `file_data` | file | Condicional | Binario multipart. Para crear correctamente un `Document` o `Skill`, envía este campo o `content` en JSON. |
</Accordion>

Si omites `scopes`, un artefacto de proyecto recibe su alcance de proyecto y un artefacto de organización recibe su alcance de organización. No puedes crear un artefacto de organización con alcances de proyecto; añádelos después con la operación de alcance.

### Artefactos de documento

Los documentos contienen contenido, los enlaces referencian artefactos existentes y las carpetas organizan artefactos dentro de una organización o un proyecto.

<Tabs>
  <Tab title="Document">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `file_name` | string | Sí | Nombre original del archivo. |
      | `content_type` | string | Sí | MIME type de `file_data`. |
      | `content_length` | integer \| null | No | Tamaño del archivo en bytes. Debe estar presente y coincidir con los bytes subidos para procesar correctamente el documento; si se omite, el artefacto se crea en estado `Error` con `ingest_status: NotApplicable`. |
      | `metadata` | object | No | Metadatos del proveedor para documentos respaldados por integraciones. |
      | `original_path` | string \| null | No | Ruta montada original cuando el artefacto se promocionó desde un thread. |
    </Accordion>

    ```bash theme={null}
    printf 'Q1 support summary.\n' > q1-support-summary.txt

    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -F 'project_id={projectID}' \
      -F 'type=Document' \
      -F 'name=Q1 Support Summary' \
      -F 'props={
        "content_type":"text/plain",
        "file_name":"q1-support-summary.txt",
        "content_length":20
      };type=application/json' \
      -F 'file_data=@./q1-support-summary.txt;type=text/plain'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_doc_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "name": "Q1 Support Summary",
        "type": "Document",
        "source": "User",
        "state": "Published",
        "ingest_status": "NotStarted",
        "props": {
          "file_name": "q1-support-summary.txt",
          "content_type": "text/plain",
          "content_length": 20
        },
        "created_at": "2026-02-08T14:30:12Z",
        "updated_at": "2026-02-08T14:31:02Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Folder">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `metadata` | object | No | Metadatos del proveedor para carpetas respaldadas por integraciones. Usa `{}` para carpetas creadas por usuarios sin metadatos. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "Folder",
        "source": "User",
        "name": "Q1 Support",
        "description": "Artifacts for Q1 support work.",
        "parent_id": null,
        "props": {}
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_folder_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "name": "Q1 Support",
        "type": "Folder",
        "source": "User",
        "state": "Published",
        "child_count": 0,
        "ingest_status": "NotApplicable",
        "props": {},
        "created_at": "2026-02-08T14:32:10Z",
        "updated_at": "2026-02-08T14:32:10Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Link">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `original_artifact_id` | string | Sí | Artefacto que se enlaza en este proyecto o carpeta. |
      | `source_artifact_id` | string | Solo respuesta | ID canónico del artefacto fuente. Lo asigna el servidor. |
      | `original_artifact_type` | string | Solo respuesta | Tipo del artefacto original. Lo asigna el servidor. |
      | `original_project_id` | string \| null | Solo respuesta | Proyecto propietario del artefacto original, si existe. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "Link",
        "source": "User",
        "name": "Q1 Support Summary (link)",
        "description": "Reference to the canonical document.",
        "parent_id": "artifact_folder_q1",
        "props": {
          "original_artifact_id": "{artifactID}"
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_link_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "name": "Q1 Support Summary",
        "parent_id": "artifact_folder_q1",
        "type": "Link",
        "source": "User",
        "state": "Published",
        "ingest_status": "NotApplicable",
        "props": {
          "source_artifact_id": "artifact_doc_q1",
          "original_artifact_id": "artifact_doc_q1",
          "original_artifact_type": "Document",
          "original_project_id": "proj_7a5c3e1b9d2f4a6c"
        },
        "created_at": "2026-02-08T14:33:22Z",
        "updated_at": "2026-02-08T14:33:22Z"
      }
      ```
    </Accordion>

    El servidor copia el nombre y el origen del artefacto original en la respuesta del enlace.
  </Tab>
</Tabs>

### Documentos IA

Los documentos IA ejecutan un flujo de trabajo de Zylon sobre uno o más artefactos para producir un resultado estructurado.

<Tabs>
  <Tab title="Summary">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `artifact_ids` | string\[] | Sí | Artefactos de entrada a resumir. |
      | `style` | string | Sí | `Expert`, `Neutral` o `Simple`. Valores obsoletos aún pueden decodificar, pero no deben usarse. |
      | `detail` | string | Sí | `KeyPoints`, `ShortPieces` o `LongPieces`. Valores obsoletos aún pueden decodificar, pero no deben usarse. |
      | `instructions` | string\[] \| null | No | Instrucciones adicionales para la generación del resumen. Omitir el campo equivale a enviar `null`. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "Summary",
        "source": "User",
        "name": "Q1 Support Summary (auto)",
        "props": {
          "artifact_ids": ["{artifactID}"],
          "style": "Neutral",
          "detail": "KeyPoints",
          "instructions": ["Focus on billing and onboarding trends."]
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_summary_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "Summary",
        "state": "Processing",
        "ingest_status": "NotApplicable",
        "props": {
          "artifact_ids": ["artifact_doc_q1"],
          "style": "Neutral",
          "detail": "KeyPoints",
          "instructions": ["Focus on billing and onboarding trends."]
        },
        "created_at": "2026-02-08T15:10:00Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Composition">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `artifact_ids` | string\[] | Sí | Artefactos de entrada para el borrador. |
      | `instructions` | string | Sí | Prompt o instrucciones de redacción. |
      | `style` | string | Sí | `Expert`, `Neutral` o `Simple`. |
      | `detail` | string | Sí | `KeyPoints`, `ShortPieces` o `LongPieces`. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "Composition",
        "source": "User",
        "name": "Q1 Support Brief",
        "props": {
          "artifact_ids": ["{artifactID}"],
          "style": "Expert",
          "detail": "LongPieces",
          "instructions": "Draft a one-page summary for leadership."
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_comp_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "Composition",
        "state": "Processing",
        "ingest_status": "NotApplicable",
        "props": {
          "artifact_ids": ["artifact_doc_q1"],
          "style": "Expert",
          "detail": "LongPieces",
          "instructions": "Draft a one-page summary for leadership."
        },
        "created_at": "2026-02-08T15:12:40Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="BulkQA">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `questions` | string\[] | Sí | Preguntas a responder. |
      | `artifact_ids` | string\[] | Sí | Artefactos de entrada para responder. |
      | `instructions` | string\[] | Sí | Restricciones o guía para las respuestas. |
      | `detail` | string | Sí | `Concise`, `Moderate` o `Comprehensive`. |
      | `style` | string | Sí | `Expert`, `Neutral` o `Simple`. |
      | `results` | object\[] | No | Resultados de respuesta generados por el servidor. Por defecto es `[]`. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "BulkQA",
        "source": "User",
        "name": "Billing FAQ",
        "props": {
          "artifact_ids": ["{artifactID}"],
          "style": "Simple",
          "detail": "Concise",
          "instructions": ["Answer using only the artifacts."],
          "questions": [
            "What are the top billing issues?",
            "How quickly were priority bugs resolved?"
          ]
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_bulkqa_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "BulkQA",
        "state": "Processing",
        "ingest_status": "NotApplicable",
        "props": {
          "artifact_ids": ["artifact_doc_q1"],
          "style": "Simple",
          "detail": "Concise",
          "instructions": ["Answer using only the artifacts."],
          "questions": [
            "What are the top billing issues?",
            "How quickly were priority bugs resolved?"
          ],
          "results": []
        },
        "created_at": "2026-02-08T15:14:10Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="ReadAndExtract">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `artifact_ids` | string\[] | Sí | Artefactos de entrada a leer. |
      | `sections` | object\[] | Sí | Objetivos de extracción. |
      | `sections[].id` | string | Sí | ID estable de la sección. |
      | `sections[].title` | string | Sí | Título de la sección. |
      | `sections[].description` | string | Sí | Qué extraer para esa sección. |
      | `results` | object\[] | Solo respuesta | Resultados extraídos por sección. |
      | `organization_context` | string \| null | Solo respuesta | Contexto de organización usado por el servidor. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "ReadAndExtract",
        "source": "User",
        "name": "Contract extraction",
        "props": {
          "artifact_ids": ["{artifactID}"],
          "sections": [
            { "title": "Term", "description": "Contract term in months", "id": "term" },
            { "title": "SLA", "description": "Support response time", "id": "sla" }
          ]
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_readextract_v3",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "ReadAndExtract",
        "state": "Processing",
        "ingest_status": "NotApplicable",
        "props": {
          "artifact_ids": ["artifact_doc_q1"],
          "sections": [
            { "title": "Term", "description": "Contract term in months", "id": "term" },
            { "title": "SLA", "description": "Support response time", "id": "sla" }
          ],
          "results": []
        },
        "created_at": "2026-02-08T15:15:55Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Analysis">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `artifact_ids` | string\[] | Sí | Artefactos de entrada a analizar. |
      | `instruction` | object \| null | No | Instrucción de análisis personalizada. Si se omite, el servidor usa su prompt de análisis por defecto. |
      | `instruction.id` | string | Sí si `instruction` está definido | ID estable de la instrucción. |
      | `instruction.prompt` | string | Sí si `instruction` está definido | Prompt usado para el análisis. |
      | `instruction.metadata` | object | No | Claves y valores de tipo string. Por defecto es `{}`. |
      | `result` | object \| null | Solo respuesta | Salida combinada del análisis. |
      | `organization_context` | string \| null | Solo respuesta | Contexto de organización usado por el servidor. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "Analysis",
        "source": "User",
        "name": "Support trend analysis",
        "props": {
          "artifact_ids": ["{artifactID}"],
          "instruction": {
            "id": "support_trends",
            "prompt": "Find the top support trends and risks.",
            "metadata": { "audience": "leadership" }
          }
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_analysis_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "Analysis",
        "state": "Processing",
        "ingest_status": "NotApplicable",
        "props": {
          "artifact_ids": ["artifact_doc_q1"],
          "instruction": {
            "id": "support_trends",
            "prompt": "Find the top support trends and risks.",
            "metadata": { "audience": "leadership" }
          }
        },
        "created_at": "2026-02-08T15:16:30Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="SmartDoc">
    <Accordion title="props body">
      La creación de SmartDoc acepta `props`, pero el servidor inicializa estos artefactos con un objeto vacío. Envía `{}`.
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "SmartDoc",
        "source": "User",
        "name": "Onboarding SmartDoc",
        "props": {}
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_smartdoc_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "SmartDoc",
        "state": "Draft",
        "ingest_status": "NotApplicable",
        "props": {},
        "created_at": "2026-02-08T15:17:20Z"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

### Otros artefactos

Los otros artefactos proporcionan herramientas, conexiones con proveedores y skills reutilizables. `private_props` se usa en artefactos **MCP**, **SqlDatabase** y `Integration` respaldados por proveedores. Consulta las formas de petición de `Integration` en las guías de [Confluence](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/confluence), [SharePoint](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/sharepoint), [Filesystem](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/filesystem) y [Claromentis](/es/v1.58/developer-manual/build-with-zylon/workspace-api/integrations/claromentis).

<Tabs>
  <Tab title="SqlDatabase">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `schemas` | string\[] \| null | No | Esquemas de base de datos a exponer. |
      | `tables` | string\[] \| null | No | Tablas de base de datos a exponer. |
      | `ssl` | boolean \| null | No | Indica si la conexión usa SSL. Valor efectivo por defecto: `true`. |
      | `enable_tables` | boolean \| null | No | Habilita descubrimiento/uso de tablas. Valor efectivo por defecto: `true`. |
      | `enable_views` | boolean \| null | No | Habilita descubrimiento/uso de vistas. Valor efectivo por defecto: `true`. |
      | `enable_procedures` | boolean \| null | No | Habilita procedimientos almacenados. Valor efectivo por defecto: `false`. |
      | `enable_functions` | boolean \| null | No | Habilita funciones. Valor efectivo por defecto: `false`. |
      | `private_props.connection_string` | string | Sí | Cadena de conexión. En ejemplos y logs, enmascara secretos. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "SqlDatabase",
        "source": "User",
        "name": "Sales database",
        "description": "Read-only reporting database.",
        "props": {
          "schemas": ["public", "analytics"],
          "tables": ["orders", "customers"],
          "ssl": true,
          "enable_tables": true,
          "enable_views": true,
          "enable_procedures": false,
          "enable_functions": false
        },
        "private_props": {
          "connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_db_sales",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "SqlDatabase",
        "state": "Published",
        "ingest_status": "NotApplicable",
        "props": {
          "schemas": ["public", "analytics"],
          "tables": ["orders", "customers"],
          "ssl": true,
          "enable_tables": true,
          "enable_views": true,
          "enable_procedures": false,
          "enable_functions": false
        },
        "created_at": "2026-02-08T15:20:05Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="McpServer">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `name` | string | Sí | Nombre del servidor MCP visible para herramientas. |
      | `tool_configuration` | object \| null | No | Configuración de allowlist de herramientas. |
      | `tool_configuration.enabled` | boolean | No | Indica si las herramientas están habilitadas. Por defecto es `true`. |
      | `tool_configuration.allowed_tools` | string\[] \| null | No | Nombres de herramientas que los clientes pueden invocar a través de este MCP server. |
      | `private_props.url` | string | Sí | URL del servidor MCP. |
      | `private_props.use_bearer_auth` | boolean | No | Indica si se autentica con bearer auth. Por defecto es `false`. |
      | `private_props.authorization_token` | string \| null | No | Token de autorización cuando el servidor espera un token custom. Enmascara el valor. |
      | `private_props.refresh_token` | string \| null | No | Refresh token de OAuth. Enmascara el valor. |
      | `private_props.client_id` | string \| null | No | Identificador de cliente OAuth. |
      | `private_props.client_secret` | string \| null | No | Secreto de cliente OAuth. Enmascara el valor. |
      | `private_props.bearer_token` | string \| null | No | Bearer token cuando bearer auth está habilitado. Enmascara el valor. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "{projectID}",
        "type": "McpServer",
        "source": "User",
        "name": "Internal tools",
        "props": {
          "name": "internal_mcp",
          "tool_configuration": {
            "enabled": true,
            "allowed_tools": ["crm_lookup", "ticket_search"]
          }
        },
        "private_props": {
          "url": "https://mcp.example.com",
          "authorization_token": "***"
        }
      }'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_mcp_internal",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "McpServer",
        "state": "Published",
        "ingest_status": "NotApplicable",
        "props": {
          "name": "internal_mcp",
          "tool_configuration": {
            "enabled": true,
            "allowed_tools": ["crm_lookup", "ticket_search"]
          }
        },
        "created_at": "2026-02-08T15:22:30Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Skill">
    <Accordion title="props body">
      | Campo | Tipo | Obligatorio | Descripción |
      | - | - | - | - |
      | `skill_id` | string \| null | No | ID de skill generado por el servidor. Omítelo al crear una skill. |
      | `versions` | string\[] | Solo respuesta | Versiones disponibles de la skill. |
      | `current_version` | string \| null | Solo respuesta | Versión activa de la skill. |
      | `content_md5` | string \| null | No | Hash generado por el servidor. Omítelo al crear una skill. |
      | `name` | string | Sí | Nombre estable de la skill. |
      | `display_title` | string | Sí | Título que se muestra en Workspace. |
      | `display_description` | string \| null | No | Descripción legible. |
      | `source` | string | No | `custom`, `anthropic` o `zylon`. Por defecto es `custom`. |
      | `loading` | string | No | `lazy` o `eager`. Por defecto es `lazy`. |
    </Accordion>

    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -F 'project_id={projectID}' \
      -F 'type=Skill' \
      -F 'name=Ticket triage' \
      -F 'props={
        "name":"ticket-triage",
        "display_title":"Ticket triage",
        "display_description":"Classify and route support tickets.",
        "source":"custom",
        "loading":"lazy"
      };type=application/json' \
      -F 'file_data=@./skill.zip;type=application/zip'
    ```

    <Accordion title="Ejemplo de respuesta">
      ```json theme={null}
      {
        "id": "artifact_skill_triage",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "Skill",
        "source": "User",
        "state": "Published",
        "ingest_status": "NotApplicable",
        "props": {
          "skill_id": "skill_ticket_triage",
          "versions": ["1"],
          "current_version": "1",
          "content_md5": "{CONTENT_MD5}",
          "name": "ticket-triage",
          "display_title": "Ticket triage",
          "display_description": "Classify and route support tickets.",
          "source": "custom",
          "loading": "lazy"
        }
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## Trabajar con artefactos

### Listar artefactos

Con `x-org`, el listado queda limitado a esa organización y no admite `organization_id`. Sin `x-org`, los operadores y superadministradores pueden seleccionar una organización con `organization_id`; si lo omiten, el backend busca en las organizaciones a las que tienen acceso. `project_id` requiere una organización seleccionada.

<Accordion title="Parametros del endpoint">
  | Parámetro de consulta | Tipo | Obligatorio | Descripción |
  | - | - | - | - |
  | `organization_id` | string | Condicional | Organización que se consulta. Omítelo al usar `x-org`; sin esa cabecera, solo pueden enviarlo operadores y superadministradores. |
  | `project_id` | string | No | Limita el listado a un proyecto. Si se envía junto con `organization_id`, debe pertenecer a esa organización. |
  | `state` | string | No | Valores separados por comas de `Initializing`, `Processing`, `Draft`, `Deleted`, `Published`, `Unavailable` y `Error`. Por defecto es `Published,Processing`. |
  | `source` | string | No | Orígenes separados por comas, como `User`, `SharePoint`, `Confluence`, `Claromentis` o `FileSystem`. |
  | `ingest_status` | string | No | Valores separados por comas de `NotApplicable`, `NotStarted`, `Processing`, `Parsing`, `Storing`, `Done` y `Error`. Por defecto incluye todos. |
  | `type` | string | No | Tipos de artefacto separados por comas. |
  | `scopes` | JSON array | No | Filtros de alcance. Cada elemento requiere `scope_type`, `scope_id` y el booleano `enabled`. `ws_auto_select` es opcional y vale `false` por defecto, pero no interviene en el filtrado. |
  | `parent_id` | string | No | Limita los resultados a hijos directos de un artefacto padre. |
  | `include_descendants` | boolean | No | Incluye todo el subárbol bajo `parent_id`; si no hay padre, incluye todos los descendientes del alcance seleccionado. |
  | `filter_by_text` | string | No | Búsqueda de texto sobre nombres de artefactos. |
  | `keep_ancestors` | boolean | No | Incluye los ancestros de los artefactos que coinciden con la consulta completa. |
  | `resolve_links` | boolean | No | Resuelve artefactos Link en listados de proyecto. Sin `parent_id`, solo añade sus descendientes cuando `include_descendants=true`; con un Link como padre, devuelve sus hijos directos o todo su subárbol según `include_descendants`. |
  | `sub_type` | string | No | Tipos separados por comas para filtrar destinos de enlaces mediante `props.original_artifact_type`; también se conservan los artefactos sin esa propiedad. |
  | `include` | string | No | Lista separada por comas de `Account`, `Project`, `Organization`, `Scopes` y `Relationships`. Usa `Account` para incluir detalles del creador. |
  | `created_by` | string | No | ID de la cuenta que creó los artefactos. |
  | `created_by_state` | string | No | Estado de la cuenta creadora: `Active` o `Inactive`. |
  | `order_by` | string | No | `Alphabetical` o `CreatedAt`. |
  | `order` | string | No | `ASC` o `DESC`. Por defecto es `ASC`. |
  | `start_date`, `end_date` | integer | No | Límites inclusivos de fecha de creación en milisegundos desde Unix epoch. |
  | `page` | integer | No | Número de página basado en cero. No puede combinarse con parámetros de cursor. |
  | `page_size` | integer | No | Elementos por página cuando se usa `page`. Por defecto es `50`; la paginación por cursor usa `first` o `last`. |
  | `page_order` | string | No | Orden por ID para paginación absoluta: `ASC` o `DESC`. Por defecto es `ASC`. |
  | `after`, `before` | string | No | Cursores de ID de artefacto para paginación hacia delante o hacia atrás. |
  | `first`, `last` | integer | No | Límite positivo de resultados después o antes de un cursor. |
  | `total_count` | boolean | No | Incluye `total_count` en la respuesta. Por defecto es `false`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact?project_id={projectID}&page=0&page_size=20&total_count=true&parent_id={artifactID}&include_descendants=false&include=Account,Scopes" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "data": [
      {
        "id": "artifact_doc_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "name": "Q1 Support Summary",
        "type": "Document",
        "source": "User",
        "state": "Published",
        "ingest_status": "Done",
        "parent_id": "artifact_folder_q1",
        "child_count": 0,
        "keep_file_after_ingestion": true,
        "scopes": [
          {
            "scope_type": "project",
            "scope_id": "proj_7a5c3e1b9d2f4a6c",
            "enabled": true,
            "ws_auto_select": false
          }
        ],
        "created_by": {
          "id": "acct_6c8a1f3b2d4e5f7a",
          "state": "Active",
          "email": "sasha@example.com",
          "name": "Sasha Patel",
          "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
          "provider": "Credentials",
          "roles": ["Workspace"],
          "created_at": "2026-02-08T14:12:45Z",
          "updated_at": "2026-02-08T14:12:45Z"
        },
        "created_at": "2026-02-08T14:30:12Z",
        "updated_at": "2026-02-08T14:31:02Z"
      }
    ],
    "has_next_page": false,
    "has_previous_page": false,
    "total_count": 1
  }
  ```
</Accordion>

La respuesta paginada también devuelve `next_cursor` y `previous_cursor` cuando esos cursores están disponibles. `has_next_page` y `has_previous_page` siempre están presentes; `total_count` solo se devuelve al enviar `total_count=true`.

### Obtener un artefacto

El servidor obtiene la organización y el proyecto del artefacto almacenado. No envíes esos identificadores en la ruta.

<Accordion title="Parámetros del endpoint">
  | Tipo | Nombre | Obligatorio | Descripción |
  | - | - | - | - |
  | Path | `artifactID` | Sí | Identificador del artefacto. |
  | Query | `include_references` | No | Incluye referencias. Por defecto es `true`. |
  | Query | `include_relationships` | No | Incluye relaciones. Si se omite, usa el valor de `include_references`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}?include_references=true&include_relationships=true" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "id": "artifact_doc_q1",
    "project_id": "proj_7a5c3e1b9d2f4a6c",
    "name": "Q1 Support Summary",
    "type": "Document",
    "source": "User",
    "state": "Published",
    "ingest_status": "Done",
    "parent_id": "artifact_folder_q1",
    "child_count": 0,
    "props": {
      "file_name": "q1-support-summary.txt",
      "content_type": "text/plain",
      "content_length": 20
    },
    "keep_file_after_ingestion": true,
    "scopes": [
      {
        "scope_type": "project",
        "scope_id": "proj_7a5c3e1b9d2f4a6c",
        "enabled": true,
        "ws_auto_select": false
      }
    ],
    "created_by": {
      "id": "acct_6c8a1f3b2d4e5f7a",
      "state": "Active",
      "email": "sasha@example.com",
      "name": "Sasha Patel",
      "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
      "provider": "Credentials",
      "roles": ["Workspace"],
      "created_at": "2026-02-08T14:12:45Z",
      "updated_at": "2026-02-08T14:12:45Z"
    },
    "created_at": "2026-02-08T14:30:12Z",
    "updated_at": "2026-02-08T14:31:02Z"
  }
  ```
</Accordion>

| Campo de respuesta | Tipo | Descripción |
| - | - | - |
| `id` | string | ID del artefacto. |
| `parent_id` | string \| null | ID del artefacto padre cuando está anidado. |
| `child_count` | integer | Número de hijos directos. |
| `project_id` | string \| null | ID del proyecto, o `null` para un artefacto de organización. |
| `project` | object \| null | Proyecto expandido cuando se solicita. |
| `organization` | object \| null | Organización expandida cuando se solicita. |
| `name` | string | Nombre del artefacto. |
| `description` | string \| null | Descripción del artefacto. |
| `type` | string | Tipo de artefacto. |
| `source` | string | Origen del artefacto. |
| `state` | string | `Initializing`, `Processing`, `Draft`, `Deleted`, `Published`, `Unavailable` o `Error`. |
| `error` | string \| null | Código de error de ingesta o procesamiento. |
| `ingest_status` | string | `NotApplicable`, `NotStarted`, `Processing`, `Parsing`, `Storing`, `Done` o `Error`. |
| `ingest_warnings` | string\[] \| null | Advertencias no fatales de ingesta. |
| `ingest_progress` | number \| null | Progreso de ingesta cuando está disponible. |
| `integration_id` | string \| null | ID de integración para artefactos respaldados por integraciones. |
| `external_url` | string \| null | URL externa cuando existe. |
| `props` | object | Configuración pública específica del tipo. |
| `file_uri` | string \| null | URL pública temporal del archivo cuando está disponible. |
| `artifact_references` | object\[] \| null | Referencias cuando `include_references=true`. |
| `artifact_relationships` | object\[] \| null | Relaciones publicadas cuando `include_relationships=true`. |
| `artifact_relationships[].node_id` | string | Identificador del nodo de artefacto relacionado. |
| `artifact_relationships[].node_type` | string | Tipo del nodo de artefacto relacionado. |
| `keep_file_after_ingestion` | boolean | Indica si se conserva el archivo subido. |
| `created_by` | object \| null | `AccountDTO` del creador. Se devuelve en el detalle del artefacto y en listados con `include=Account`. |
| `created_at` | timestamp | Fecha de creación. |
| `updated_at` | timestamp | Fecha de última actualización. |
| `etag` | string \| null | Etiqueta de versión cuando está disponible. |
| `scopes` | object\[] \| null | Alcances del artefacto. Cada elemento contiene `scope_type`, `scope_id`, `enabled` y `ws_auto_select`. |

### Actualizar un artefacto

<Accordion title="Parametros del endpoint">
  | Campo | Tipo | Obligatorio | Descripción |
  | - | - | - | - |
  | `artifactID` | path | Sí | Identificador del artefacto. |
  | `name` | string | No | Nuevo nombre del artefacto. |
  | `parent_id` | string | No | Mueve un artefacto de contenido o árbol bajo este artefacto padre. No lo uses en artefactos MCP o de base de datos. |
  | `reset_parent_id` | boolean | No | Ponlo a `true` para mover un artefacto de contenido o árbol a la raíz de su árbol de proyecto u organización. Por defecto es `false`. |
  | `external_url` | string | No | Sustituye la URL externa. |
  | `props` | object | No | Sustituye o actualiza la configuración pública específica del tipo. También se acepta el alias heredado `config`. |
  | `description` | string | No | Sustituye la descripción. |
  | `content` | string | No | Contenido de texto UTF-8 al usar JSON. Para multipart, envía el binario como `file_data`. |
  | `private_props` | object | No | Configuración privada para artefactos `Integration` respaldados por proveedores, MCP y de base de datos SQL. |
  | `scopes` | object\[] | No | Cambios de alcance. Cada elemento usa `scope_type`, `scope_id`, y opcionalmente `enabled`, `ws_auto_select` o `delete`. |
  | `file_data` | file | No | Archivo de reemplazo al usar multipart. Los demás campos se envían como campos del formulario. |
</Accordion>

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Support Summary (final)",
    "description": "Finalized weekly summary notes.",
    "parent_id": "artifact_folder_q1",
    "reset_parent_id": false,
    "content": "Ticket volume rose 12% week-over-week..."
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "id": "artifact_doc_q1",
    "name": "Q1 Support Summary (final)",
    "description": "Finalized weekly summary notes.",
    "parent_id": "artifact_folder_q1",
    "type": "Document",
    "source": "User",
    "ingest_status": "Done",
    "updated_at": "2026-02-08T14:45:21Z"
  }
  ```
</Accordion>

<Tip>
  Usa `parent_id` para mover un artefacto dentro de una carpeta. Usa `reset_parent_id: true` para quitar el padre actual y moverlo a la raíz de su árbol de proyecto u organización.
</Tip>

### Validar antes de crear o actualizar

La validación está implementada para artefactos `Skill` y `SqlDatabase`. Usa `POST /api/v1/app/artifact/validate` con el mismo cuerpo de creación que enviarías a `POST /api/v1/app/artifact`. Para validar la actualización de uno de esos artefactos, usa `POST /api/v1/app/artifact/{artifactID}/validate` con el mismo cuerpo JSON que enviarías a `PUT /api/v1/app/artifact/{artifactID}`. Ninguna de las dos operaciones guarda cambios.

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "SqlDatabase",
    "name": "Sales database",
    "props": {
      "ssl": true,
      "enable_tables": true
    },
    "private_props": {
      "connection_string": "{DATABASE_CONNECTION_STRING}"
    }
  }'
```

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "props": {
      "ssl": true,
      "enable_tables": true
    },
    "private_props": {
      "connection_string": "{DATABASE_CONNECTION_STRING}"
    }
  }'
```

Ambas rutas devuelven el mismo modelo de validación:

```json theme={null}
{
  "valid": true,
  "errors": [],
  "warnings": []
}
```

La respuesta contiene `valid`, `errors` y `warnings`, además del campo opcional `data`. Cada error o advertencia contiene `type`, `message` y, opcionalmente, `params`. La validación de skills puede devolver `name` y `description` analizados dentro de `data`.

### Añadir o eliminar un alcance

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/scope" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "project",
    "scope_id": "{projectID}",
    "enabled": true,
    "ws_auto_select": false
  }'
```

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `scope_type` | string | Sí | `organization` o `project`. |
| `scope_id` | string | Sí | ID de la organización o el proyecto del alcance. |
| `enabled` | boolean | No | Habilita o deshabilita el artefacto en ese alcance. |
| `ws_auto_select` | boolean | No | Permite que Workspace seleccione automáticamente el artefacto en ese alcance. |
| `delete` | boolean | No | Usa `true` para eliminar el alcance. Por defecto es `false`. |

La respuesta es el artefacto actualizado con su lista `scopes`.

### Reintentar la creación de un artefacto

`POST /api/v1/app/artifact/{artifactID}/retry` elimina el artefacto original y crea uno nuevo con un cuerpo de creación completo. `organization_id` y `project_id` deben coincidir con los del artefacto original.

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/retry" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Folder",
    "name": "Q1 Support (retry)",
    "props": {}
  }'
```

La respuesta es el artefacto de reemplazo.

### Eliminar un artefacto

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  [
    {
      "id": "artifact_doc_q1",
      "state": "Deleted"
    }
  ]
  ```
</Accordion>

La respuesta es una lista porque la eliminación puede afectar a artefactos descendientes.

### Descargar contenido sin procesar

Sin la cabecera `Content-Disposition`, o con `Content-Disposition: inline`, la respuesta es una cadena con una URL prefirmada. Para un artefacto Link disponible, tanto este modo como `Content-Disposition: attachment` resuelven el artefacto original antes de devolver su URL o sus bytes:

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/download" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Ejemplo de respuesta">
  ```text theme={null}
  https://storage.example.com/artifacts/artifact_doc_q1?signature=...
  ```
</Accordion>

Para recibir los bytes directamente, envía `Content-Disposition: attachment`:

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/download" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Disposition: attachment" \
  --output q1-support-summary.txt
```

### Obtener contenido procesado

Este endpoint solo está disponible cuando el artefacto tiene un índice vectorial inicializado.
En la práctica, esto suele implicar documentos de conectores o artefactos con indexación ya completada.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/parsed-content" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Ejemplo de respuesta">
  ```text theme={null}
  # Q1 Support Summary

  Billing issues drove 38% of support cases.
  ```
</Accordion>

### Sincronizar un artefacto

Este endpoint se utiliza principalmente con artefactos de integración (SharePoint, Confluence, Claromentis o FileSystem).

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/sync" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Accept: text/event-stream"
```

El cuerpo de la petición está vacío. La respuesta es un stream SSE emitido por el proceso de sincronización de la integración.

<Accordion title="Campos de eventos de sincronización">
  | Campo JSON | Tipo | Presente en | Descripción |
  | - | - | - | - |
  | `type` | string | Todos los eventos | `sync_started`, `sync_progress`, `sync_completed` o `sync_error`. |
  | `current_artifact_count` | integer | `sync_started` | Número de artefactos existentes. Por defecto es `0`. |
  | `integration_item_count` | integer \| null | `sync_started` | Número total de elementos del proveedor cuando se conoce. |
  | `integration_item` | object \| null | `sync_progress` | Elemento del proveedor que se está procesando. |
  | `artifact_id` | string \| null | `sync_progress` | Identificador del artefacto afectado. |
  | `artifact` | object \| null | `sync_progress` | Artefacto público afectado cuando se incluye. |
  | `op` | string | `sync_progress` | `Added`, `Removed`, `Skipped`, `Updated`, `Recreated` o `Error`. |
  | `progress` | number | `sync_progress` | Valor de progreso. Por defecto es `0`. |
  | `message` | string | `sync_error` | Mensaje de error. |
</Accordion>

<Accordion title="Ejemplo de stream">
  ```text theme={null}
  event: SyncEvent
  data: {"type":"sync_started","current_artifact_count":12,"integration_item_count":40}

  event: SyncEvent
  data: {"type":"sync_progress","artifact_id":"artifact_doc_q1","op":"Updated","progress":0.42}

  event: SyncEvent
  data: {"type":"sync_completed"}
  ```
</Accordion>

### Ingerir desde un artefacto de integración

`POST /api/v1/app/artifact/{artifactID}/ingest` inicia la ingesta desde el artefacto de integración indicado por `artifactID`. El cuerpo JSON requiere `project_id` y los demás campos dependen del proveedor. El ejemplo selecciona un espacio de Confluence; consulta la guía de cada integración para ver sus campos completos. La respuesta es un stream SSE.

<Accordion title="Parámetros del endpoint">
  | Tipo | Nombre | Obligatorio | Descripción |
  | - | - | - | - |
  | Path | `artifactID` | Sí | Identificador del artefacto de integración. |
  | Body | `project_id` | Sí | Proyecto de destino de la ingesta. |
  | Body | Campos del proveedor | Condicional | Parámetros de selección o ingesta requeridos por la integración. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{artifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "space_ids": ["ENG"]
  }'
```

### Actualizar artefactos en bloque

Usa el endpoint de actualización en bloque para aplicar la misma forma de cuerpo de `PUT /api/v1/app/artifact/{artifactID}` a varios artefactos.

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Body | `artifacts` | Sí | Lista de actualizaciones de artefactos. |
  | Body | `artifacts[].artifactId` | Sí | Identificador del artefacto a actualizar. |
  | Body | `artifacts[].update` | Sí | Cuerpo de actualización con los mismos campos que `PUT /api/v1/app/artifact/{artifactID}`. |
</Accordion>

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/bulk" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifacts": [
      {
        "artifactId": "artifact_doc_q1",
        "update": {
          "parent_id": "artifact_folder_q1",
          "reset_parent_id": false,
          "description": "Moved into Q1 folder."
        }
      }
    ]
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  [
    {
      "id": "artifact_doc_q1",
      "parent_id": "artifact_folder_q1",
      "description": "Moved into Q1 folder.",
      "type": "Document",
      "state": "Published",
      "ingest_status": "Done",
      "updated_at": "2026-02-08T15:20:00Z"
    }
  ]
  ```
</Accordion>

### Eliminar artefactos en bloque

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Body | `artifact_ids` | Sí | Identificadores de artefactos a eliminar. |
</Accordion>

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/artifact/bulk" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact_ids": ["artifact_doc_q1", "artifact_link_q1"]
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  [
    {
      "id": "artifact_doc_q1",
      "state": "Deleted"
    },
    {
      "id": "artifact_link_q1",
      "state": "Deleted"
    }
  ]
  ```
</Accordion>

## Comprobar artefactos enlazados antes de modificar

Usa este endpoint antes de cambiar un artefacto cuando necesites comprobar si otros artefactos enlazados dependen de él.

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Query | `created_by` | No | ID de la cuenta que creó los artefactos a comprobar. |
  | Query | `project_id` | No | ID del proyecto donde comprobar artefactos enlazados. |
  | Query | `artifact_id` | No | ID del artefacto donde comprobar artefactos enlazados. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/resource/is-safe-to-modify?project_id={projectID}&artifact_id={artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "has_linked_artifacts": false
  }
  ```
</Accordion>

## Errores y casos límite

* **Códigos de error de artefacto**: el campo `error` refleja fallos de ingesta:

| valor `error` | Significado |
| - | - |
| `InvalidExtension` | Extensión de archivo no admitida. |
| `MismatchedType` | El tipo de archivo no coincide con el tipo declarado. |
| `Malformed` | Archivo corrupto o ilegible. |
| `Encrypted` | Archivo protegido con contraseña. |
| `ParsingFailure` | El extractor no pudo analizar el archivo. |
| `MaxNodes` | Documento demasiado grande o complejo para el análisis. |
| `NoValidFile` | No se encontró un archivo válido. |
| `NoValidNodes` | No se pudo extraer contenido analizable. |
| `InternalError` | Fallo inesperado en la ingesta. |
| `Unknown` | Fallo no clasificado. |

Si `ingest_status` es `Error`, corrige el archivo y reintenta o sustituye el artefacto. Para artefactos de integración, corrige el origen y vuelve a sincronizar.

* **Advertencias**: `ingest_warnings` puede incluir valores como `BigSize`, `UnprocessableContent` o `NoContent` para indicar problemas no fatales.
* **400**: en creación falta `organization_id` o `x-org`, se usa `project_id` sin una organización seleccionada o ya hay una sincronización en curso.
* **401**: token ausente o no válido.
* **403**: permisos insuficientes o combinación no permitida de `organization_id` con `x-org`.
* **404**: artefacto o proyecto no encontrado.
* Para archivos de más de 250 MB, el backend conserva únicamente el registro del artefacto con la advertencia `UnprocessableContent`; no almacena los bytes subidos ni inicia la ingesta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.