> ## 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.

# Chats

> Hilos, interacciones y chat de una sola llamada.

<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>

Los chats en la Workspace API se organizan alrededor de **hilos** e **interacciones**:

| Concepto | Significado |
| - | - |
| **Thread** | Contenedor de conversación dentro de un proyecto. |
| **Interaction** | Interacción individual dentro del hilo. |
| **Chat** | Solicitud de una sola llamada que **no** crea un hilo. |

Usa hilos cuando necesitas historial y seguimiento. Usa interacciones para enviar un nuevo turno a un hilo. Usa el endpoint de chat para solicitudes de un solo turno.

<Warning>
  En 1.58, `created_by.id` identifica una cuenta, no un miembro del espacio de trabajo. Ambos IDs son UUIDs. Actualiza las comparaciones y busquedas guardadas; consulta la [migracion de IDs de cuenta](/es/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#ids-de-cuenta-y-campos-renombrados).
</Warning>

## Solicitud básica y respuesta

Crea una interaccion con `POST /api/v1/app/thread/{threadID}/interaction`. Envia exactamente un nuevo mensaje de usuario; el servidor incorpora el historial del hilo. La respuesta es `200` SSE con un evento inicial `interaction` y eventos de mensaje que terminan en `done`.

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo; se toma de la URL. |
  | Body | `thread_id` | No | Opcional; el ID de hilo de la URL tiene prioridad. |
  | Body | `pgpt` | Si | Exactamente un mensaje en `messages`, con `role: "user"`. Usa los campos de solicitud de Messages. |
  | Body | `artifacts` | No | Selecciones por alcance; consulta Seleccionar artefactos. |
  | Body | `agent` | No | `Default` (predeterminado) o `ProjectDeepResearch`. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "artifacts": {
      "document": [
        {
          "scope": "project",
          "artifacts_ids": [
            "{artifactID}"
          ]
        }
      ]
    },
    "agent": "Default",
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarize the artifact in three bullets."
            }
          ]
        }
      ],
      "max_tokens": 120,
      "temperature": 0.2
    }
  }'
```

El stream siguiente esta abreviado. Lee el evento inicial `interaction` para obtener el ID de la interaccion guardada y procesa los eventos de mensaje hasta `done`.

<Accordion title="Ejemplo de stream">
  ```text theme={null}
  event: interaction
  data: {"type":"interaction","interaction":{"id":"{interactionID}","project_id":"{projectID}","thread_id":"{threadID}","state":"Processing","user_input":{"role":"user","content":[{"type":"text","text":"Summarize the artifact in three bullets."}]},"created_at":"2026-02-08T14:41:10Z"}}

  event: message_start
  data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[]}}

  event: content_block_delta
  data: {"type":"content_block_delta","index":0,"block_id":"block_example","delta":{"type":"text_delta","text":"Ticket volume decreased this week."}}

  event: message_stop
  data: {"type":"message_stop"}

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

### Campos de respuesta de interaccion

Los campos nulos pueden omitirse. Los mensajes anidados siguen [Messages](/es/v1.58/developer-manual/build-with-zylon/working-with-messages) y las cuentas siguen [Miembros del espacio de trabajo](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user).

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | ID de interaccion generado por el servidor. |
| `project_id` | string | Proyecto de la interaccion. |
| `thread_id` | string or null | Hilo al que pertenece, cuando existe. |
| `state` | string | `Processing`, `Completed`, `Error`. |
| `user_input` | object | Mensaje del usuario: `role` y bloques `content`. |
| `assistant_output` | object or null | Mensaje del asistente cuando existe; consulta el modelo de respuesta de Messages. |
| `artifacts` | object or null | Selecciones de artefactos descritas abajo. |
| `created_at` | timestamp | Fecha de creacion generada por el servidor. |
| `created_by` | object or null | Datos de cuenta al pedir `include=Account` en la lista de interacciones. El ID del creador es un ID de cuenta. |
| `pgpt` | object or null | Solicitud de chat guardada; consulta el modelo de solicitud de Messages. |

## Seleccionar artefactos

Usa `artifacts` en las solicitudes de interaccion y de chat con envoltorio. Contiene arrays opcionales `document`, `connector`, `skill` y `agent_flow`. Cada array contiene selecciones por alcance `organization` o `project`.

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Body | `artifacts.document` | No | Documentos, texto inline, carpetas y enlaces. |
  | Body | `artifacts.connector` | No | Bases de datos SQL y servidores MCP. |
  | Body | `artifacts.skill` | No | Skills. |
  | Body | `artifacts.agent_flow` | No | Artefactos Analysis, BulkQA, Composition, ReadAndExtract, SmartDoc y Summary. |
  | Body | `artifacts.<category>[].scope` | Si | `organization` o `project`. |
  | Body | `artifacts.<category>[].all_artifacts` | No | Selecciona todos los artefactos habilitados de ese alcance. Por defecto null. |
  | Body | `artifacts.<category>[].artifacts_ids` | No | Array de IDs de artefactos seleccionados. El nombre exacto incluye la `s`: `artifacts_ids`. Por defecto null. |
</Accordion>

No combines `all_artifacts: true` con un array `artifacts_ids` no vacio. Cada categoria admite como maximo una entrada por alcance. La seleccion `project` usa el proyecto del hilo o el `project_id` del chat con envoltorio; sin contexto de proyecto, `all_artifacts` para ese alcance no selecciona nada. `artifact_ids` y `all_artifacts` en el nivel superior no son el modelo de seleccion actual.

```json theme={null}
{
  "artifacts": {
    "document": [
      {
        "scope": "project",
        "artifacts_ids": [
          "{artifactID}"
        ]
      },
      {
        "scope": "organization",
        "all_artifacts": false,
        "artifacts_ids": []
      }
    ]
  }
}
```

Los artefactos de organizacion disponibles se incluyen por defecto en cada categoria sin una entrada explicita `organization`. Para excluir ese valor predeterminado de una categoria, envia una entrada de organizacion con `all_artifacts: false` y `artifacts_ids: []`. Los archivos disponibles producidos en turnos anteriores del mismo hilo tambien siguen utilizables.

## Agregar media al chat

Si el modelo seleccionado soporta entrada multimodal, puedes enviar media en `pgpt.messages[].content[]` (la misma forma de request usada por interacciones en hilo y por chat de una sola llamada).

Puedes combinar múltiples bloques de contenido en un mismo mensaje. Tipos principales en el esquema:

| Tipo | Uso típico | Campos requeridos | Notas |
| - | - | - | - |
| `text` | Prompt/entrada en texto plano | ninguno | Usa `text`; soporta metadata opcional de `citations`. |
| `image` | Imagen adjunta | `data` | `data` puede ser base64 o URL; `mime_type` es opcional. |
| `audio` | Audio adjunto | `data` | `data` puede ser base64 o URL; `mime_type` es opcional. |
| `binary` | Payload binario genérico | `data`, `mime_type` | `filename` opcional. |
| `file` | Bloque de archivo/documento | `content` | `content_type` y `doc_metadata` opcionales. |
| `tool_use` | Llamada a una herramienta personalizada | `id`, `name`, `input` | Llamada a una herramienta que ejecuta tu aplicación. Devuelve un bloque `tool_result`. |
| `server_tool_use` | Llamada a una herramienta integrada | `id` (prefijo `srvtoolu_`), `name`, `input` | Zylon ejecutó la herramienta. Va seguido de su bloque de resultado (`server_tool_result`, `web_search_tool_result`, `web_fetch_tool_result`, `bash_code_execution_tool_result` o `text_editor_code_execution_tool_result`). |

`start_timestamp`, `stop_timestamp` y `_meta` son opcionales en todos los bloques.

<Accordion title="Ejemplo de bloques de contenido">
  ```json theme={null}
  [
    { "type": "text", "text": "Summarize this image." },
    { "type": "image", "data": "<BASE64_OR_URL>", "mime_type": "image/png" },
    { "type": "audio", "data": "<BASE64_OR_URL>", "mime_type": "audio/mpeg" },
    { "type": "binary", "data": "<BASE64_OR_URL>", "mime_type": "application/octet-stream", "filename": "blob.bin" },
    {
      "type": "file",
      "content": "<BASE64_OR_TEXT_FILE_CONTENT>",
      "content_type": "application/pdf",
      "doc_metadata": { "file_name": "contract.pdf", "file_type": "pdf" }
    },
    {
      "type": "source",
      "sources": [
        {
          "type": "context.website",
          "url": "https://example.com/report",
          "title": "Quarterly Report",
          "description": "Public report page"
        },
        {
          "type": "context.chunk",
          "id": "chunk_01",
          "score": 0.92,
          "text": "Support backlog dropped 8% week-over-week",
          "document": {
            "object": "artifact",
            "artifact": "artifact_123",
            "doc_metadata": { "file_name": "support.csv", "file_type": "csv" }
          }
        }
      ]
    },
    { "type": "server_tool_use", "id": "srvtoolu_123", "name": "semantic_search", "input": { "query": "billing issues" } },
    {
      "type": "server_tool_result",
      "tool_use_id": "srvtoolu_123",
      "content": [{ "type": "text", "text": "Found 5 matching passages." }],
      "is_error": false
    },
    { "type": "thinking", "thinking": "I should compare the latest week to the previous one." },
    {
      "type": "tldr",
      "content": [
        { "type": "text", "text": "User: Analyze support trend" },
        { "type": "text", "text": "Assistant: Backlog decreased 8%" }
      ]
    }
  ]
  ```
</Accordion>

Ejemplo de interacción con imagen + texto y flags de ejecución:

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo; se toma de la URL. |
  | Body | `thread_id` | No | Opcional; el ID de hilo de la URL tiene prioridad. |
  | Body | `pgpt` | Si | Exactamente un mensaje en `messages`, con `role: "user"`. Usa los campos de solicitud de Messages. |
  | Body | `artifacts` | No | Selecciones por alcance; consulta Seleccionar artefactos. |
  | Body | `agent` | No | `Default` (predeterminado) o `ProjectDeepResearch`. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "artifacts": {
      "document": [{ "scope": "project", "all_artifacts": true }]
    },
    "agent": "Default",
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "image",
              "data": "<BASE64_IMAGE_DATA>",
              "mime_type": "image/png"
            },
            {
              "type": "text",
              "text": "What do you see here?"
            }
          ]
        }
      ],
      "system": {
        "use_default_prompt": true,
        "citations": {
          "enabled": true
        }
      },
      "thinking": {
        "enabled": true
      }
    }
  }'
```

* `system.citations.enabled`: pide al modelo incluir referencias/citas cuando estén disponibles.
* `thinking.enabled`: activa modo de razonamiento profundo; puede tardar más pero suele mejorar la calidad.

## Crear o listar hilos

Crear un hilo en un proyecto:

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `projectID` | Si | Identificador del proyecto. |
  | Body | `name` | Si | Nombre del hilo. |
  | Body | `visibility` | Si | `Public` o `Private`. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Support Brief",
    "visibility": "Private"
  }'
```

Listar hilos:

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `projectID` | Si | Identificador del proyecto. |
  | Query | `state` | No | Estados de hilo separados por comas: `Active` y `Deleted`. |
  | Query | `include` | No | Datos relacionados que se incluirán, separados por comas: `Account` y `ReadState`. |
  | Query | `page` | No | Número de página absoluto, empezando en 1. |
  | Query | `page_size` | No | Número de elementos por página. |
  | Query | `page_order` | No | `ASC` o `DESC`. |
  | Query | `after` | No | Cursor o valor desde el que paginar hacia delante. |
  | Query | `before` | No | Cursor o valor desde el que paginar hacia atrás. |
  | Query | `first` | No | Limita a los primeros N elementos después de un cursor. |
  | Query | `last` | No | Limita a los últimos N elementos antes de un cursor. |
  | Query | `total_count` | No | Incluye el total de resultados en la respuesta. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/thread?page=1&page_size=20&include=ReadState" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "data": [
      {
        "id": "{threadID}",
        "project_id": "{projectID}",
        "name": "Weekly Support Brief",
        "state": "Active",
        "visibility": "Private",
        "read_state": {
          "last_read_at": "2026-02-08T14:41:10Z",
          "has_unread_response": false
        }
      }
    ],
    "has_next_page": false,
    "has_previous_page": false
  }
  ```
</Accordion>

### Campos de respuesta del hilo

Crear, consultar, actualizar y eliminar devuelven este modelo de hilo con `200`. Las listas de proyecto lo incluyen en el envoltorio de paginacion compartido. Los campos nulos pueden omitirse; las respuestas de hilo no contienen `created_at`. Los datos de cuenta siguen el [modelo de cuenta del miembro](/es/v1.58/developer-manual/build-with-zylon/workspace-api/users/user).

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | ID de hilo generado por el servidor. |
| `project_id` | string | ID del proyecto al que pertenece. |
| `name` | string | Nombre del hilo. |
| `state` | string | `Active` o `Deleted`. |
| `visibility` | string | `Public` o `Private`. |
| `created_by` | object or null | Objeto de cuenta en listas de hilos con `include=Account`. Los IDs de creador son de cuenta, no de miembro del espacio de trabajo. |
| `read_state` | object or null | Presente en listas de hilos con `include=ReadState`. |
| `read_state.last_read_at` | timestamp or null | Punto de lectura de la cuenta actual; null u omitido antes de la primera lectura. |
| `read_state.has_unread_response` | boolean | True para un hilo nuevo creado por otra cuenta o una respuesta completada posterior al punto de lectura. |

Consultar `GET /app/thread/{threadID}/interaction` avanza el punto de lectura de la cuenta actual hasta las respuestas completadas de la pagina devuelta, o al menos hasta la creacion del hilo si no hay respuestas completadas. Consultar solo el detalle del hilo no marca la conversacion como leida. El estado de lectura es por cuenta.

Crea un hilo y la primera interacción en una sola petición:

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `projectID` | Si | Identificador del proyecto. |
  | Body | `thread_name` | No | Nombre del nuevo hilo. Por defecto `New Thread`. |
  | Body | `thread_visibility` | No | `Public` o `Private`; por defecto `Private`. |
  | Body | `pgpt` | Si | Exactamente un mensaje de usuario. |
  | Body | `artifacts` | No | Selecciones de artefactos por alcance. |
  | Body | `agent` | No | `Default` (predeterminado) o `ProjectDeepResearch`. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread/interaction" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "thread_name": "Weekly Support Brief",
    "thread_visibility": "Private",
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarize the artifact in three bullets."
            }
          ]
        }
      ],
      "max_tokens": 120,
      "temperature": 0.2
    }
  }'
```

Esta operacion devuelve `200` SSE con los IDs de la nueva interaccion y del hilo en el evento inicial `interaction`, seguido de eventos de mensaje y `done`. `name` y `visibility` pertenecen al cuerpo de creacion de hilo separado y no sustituyen aqui a `thread_name`, `thread_visibility` ni `pgpt`.

## Obtener un hilo

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
</Accordion>

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

Devuelve el modelo de respuesta de hilo anterior. Las relaciones `include` estan disponibles en la lista del proyecto, no en este endpoint de detalle.

## Actualizar o eliminar un hilo

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
  | Body | `name` | No | Nuevo nombre en PUT. Omite o envia null para mantenerlo. |
  | Body | `visibility` | No | Nueva visibilidad `Public` o `Private` en PUT. Omite o envia null para mantenerla. |
</Accordion>

PUT devuelve el hilo actualizado; DELETE lo elimina de forma logica y devuelve el hilo con `state: "Deleted"`. Ambos devuelven `200` JSON.

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/thread/{threadID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Support Brief",
    "visibility": "Private"
  }'
```

Eliminar un hilo:

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

## Listar u obtener interacciones

Listar interacciones de un hilo:

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
  | Query | `include` | No | Datos relacionados que se incluirán, separados por comas. Valor compatible: `Account`. |
  | Query | `page` | No | Número de página absoluto, empezando en 1. |
  | Query | `page_size` | No | Número de elementos por página. |
  | Query | `page_order` | No | `ASC` o `DESC`. |
  | Query | `after` | No | Cursor o valor desde el que paginar hacia delante. |
  | Query | `before` | No | Cursor o valor desde el que paginar hacia atrás. |
  | Query | `first` | No | Limita a los primeros N elementos después de un cursor. |
  | Query | `last` | No | Limita a los últimos N elementos antes de un cursor. |
  | Query | `total_count` | No | Incluye el total de resultados en la respuesta. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction?page=1&page_size=20&include=Account" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

Obtener una interacción:

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

## Eliminar o hacer streaming de una interacción

Cancelar una interacción en ejecución:

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/interaction/{interactionID}/cancel" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

Eliminar una interacción:

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

Streaming:

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

El stream siguiente esta abreviado. Lee el evento inicial `interaction` para obtener el ID de la interaccion guardada y procesa los eventos de mensaje hasta `done`.

<Accordion title="Ejemplo de stream">
  ```text theme={null}
  event: interaction
  data: {"type":"interaction","interaction":{"id":"{interactionID}","project_id":"{projectID}","thread_id":"{threadID}","state":"Processing","user_input":{"role":"user","content":[{"type":"text","text":"Summarize the artifact in three bullets."}]},"created_at":"2026-02-08T14:41:10Z"}}

  event: message_start
  data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[]}}

  event: content_block_delta
  data: {"type":"content_block_delta","index":0,"block_id":"block_example","delta":{"type":"text_delta","text":"Ticket volume decreased this week."}}

  event: message_stop
  data: {"type":"message_stop"}

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

## Archivos del hilo

Los endpoints de archivos usan el hilo como alcance de sesion. La subida y PUT guardan bytes; la conversion exporta o importa contenido MDX de artefactos. Envia `x-org` y un token API en cada solicitud. La subida, PUT y la exportacion desde un artefacto requieren permiso para actualizar el hilo.

### Subir un archivo

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
  | Query | `path` | No | Clave relativa a uploads, como `reports/report.mdx`. Por defecto el nombre del archivo; se normaliza el prefijo `uploads/`. |
  | Query | `namespace` | No | `session` (predeterminado), `artifacts`, `skills`. |
  | Multipart | `file` | Si | Parte de archivo con los bytes. No fijes manualmente el boundary multipart. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/upload-file?path=report.mdx&namespace=session" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -F "file=@report.mdx;type=text/plain"
```

Devuelve `200` con metadatos de archivo. La ausencia de `file` en multipart devuelve `400`.

### Guardar bytes de archivo

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
  | Path | `path` | Si | Clave de almacenamiento, con segmentos anidados como `reports/report.mdx`. |
  | Query | `namespace` | No | `session` (predeterminado), `artifacts`, `skills`. |
  | Header | `Content-Type` | No | Tipo MIME del archivo; por defecto `application/octet-stream`. |
  | Body | `file bytes` | Si | Bytes sin codificacion JSON ni multipart. |
</Accordion>

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/thread/{threadID}/put-file/reports/report.mdx?namespace=session" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: text/plain" \
  --data-binary @report.mdx
```

Devuelve `200` con metadatos de archivo. Crea las carpetas padre y sobrescribe una clave existente.

### Descargar un archivo del hilo

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
  | Query | `path` | Si | Ruta absoluta del sandbox o su ID de archivo codificado en Base64. Codifica el valor de consulta para la URL. |
  | Query | `namespace` | No | `session` (predeterminado), `artifacts`, `skills`. |
  | Query | `disposition` | No | `attachment` (predeterminado) o `inline`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}/download-file?path=%2Fmnt%2Fuser-data%2Foutputs%2Freport.mdx&namespace=session&disposition=attachment" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -o report.mdx
```

Devuelve `200` con bytes, tipo MIME inferido y `Content-Disposition`; no devuelve una URL prefirmada. La configuracion de organizacion puede denegar la descarga con `403`: outputs requiere descargas de recursos generados, uploads requiere descargas de recursos subidos y las rutas no reconocidas requieren ambos ajustes.

### Convertir un archivo del hilo en artefacto

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
  | Body | `file_id` | No | ID de archivo. Proporciona `file_id` o `path` no vacio. |
  | Body | `path` | No | Ruta absoluta o codificada en Base64. Cuando se envia, el nombre debe terminar en `.mdx`. |
  | Body | `project_id` | No | ID del proyecto de destino. Omite o envia null para crear un artefacto de organizacion; no se toma del hilo. |
  | Body | `name` | No | Nombre del artefacto; en su ausencia se usa el titulo MDX o el nombre de archivo. |
  | Body | `parent_id` | No | Aceptado pero actualmente sin efecto. Mueve el artefacto con el endpoint de actualizacion despues de convertirlo. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/convert-to-artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/mnt/user-data/outputs/report.mdx",
    "project_id": "{projectID}",
    "name": "Support report"
  }'
```

Devuelve `200` con el [modelo del artefacto](/es/v1.58/developer-manual/build-with-zylon/workspace-api/content/artifacts) creado o actualizado. El contenido debe ser MDX valido de artefacto; sus metadatos determinan el tipo y las propiedades. Fallan la ausencia de ambos selectores, las rutas no MDX o el MDX invalido. Se aplican los permisos normales de creacion y actualizacion de artefactos.

### Convertir un artefacto en archivo del hilo

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Path | `threadID` | Si | Identificador del hilo. |
  | Body | `artifact_id` | Si | Artefacto que se exporta a la sesion del hilo. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/convert-from-artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact_id": "{artifactID}"
  }'
```

Devuelve `200` con metadatos del archivo MDX exportado. Requiere permiso de lectura del artefacto y las mismas comprobaciones de descarga que el artefacto; las descargas deshabilitadas devuelven `403`.

### Respuesta de metadatos de archivo

La subida, PUT y la exportacion desde artefacto comparten esta respuesta. Los campos nulos pueden omitirse.

| Campo | Tipo | Significado |
| - | - | - |
| `id` | string | Identificador que codifica en Base64 la ruta absoluta del sandbox. |
| `created_at` | string | Fecha de creacion generada por el servidor. |
| `filename` | string | Nombre de archivo. |
| `mime_type` | string | Tipo de contenido. |
| `size_bytes` | integer | Tamano en bytes. |
| `type` | string | `file`. |
| `downloadable` | boolean | Si los metadatos marcan el archivo como descargable; tambien se aplica la politica de organizacion. |
| `namespace` | string or null | `session`, `artifacts`, `skills`. |
| `scope` | object or null | Alcance del archivo con `id` (string) y `type` (`session`, `artifacts`, `skills`). |
| `etag` | string or null | Identificador de contenido opcional. |

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "id": "L21udC91c2VyLWRhdGEvdXBsb2Fkcy9yZXBvcnQubWR4",
    "created_at": "2026-02-08T14:41:10Z",
    "filename": "report.mdx",
    "mime_type": "text/plain",
    "size_bytes": 128,
    "type": "file",
    "downloadable": true,
    "namespace": "session",
    "scope": {
      "id": "{threadID}",
      "type": "session"
    },
    "etag": "etag_example"
  }
  ```
</Accordion>

## Chat puntual

El endpoint actual devuelve `200` con `Content-Type: text/event-stream`, incluso si `pgpt.stream` es false. No crea un hilo ni una interaccion guardada. Usa el cuerpo con envoltorio para seleccionar un proyecto o artefactos. Se sigue aceptando una solicitud de Messages plana para un chat solo de organizacion.

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Body | `pgpt` | Si | Solicitud de Messages con exactamente un mensaje de usuario. `private_gpt` es un alias aceptado. |
  | Body | `project_id` | No | Contexto de proyecto opcional. Omite o envia null para un chat solo de organizacion. |
  | Body | `artifacts` | No | Selecciones de artefactos por alcance descritas arriba. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/chat" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "artifacts": {
      "document": [
        {
          "scope": "project",
          "artifacts_ids": [
            "{artifactID}"
          ]
        }
      ]
    },
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Draft a two-sentence update on this week support backlog."
            }
          ]
        }
      ],
      "max_tokens": 64,
      "temperature": 0.3
    }
  }'
```

Consume los eventos de mensaje hasta `done`; esta operacion no emite un evento `interaction` guardado. La desconexion cancela la solicitud activa. Consulta [Messages](/es/v1.58/developer-manual/build-with-zylon/working-with-messages) para los campos anidados de solicitud y respuesta.

<Accordion title="Ejemplo de stream">
  ```text theme={null}
  event: message_start
  data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[]}}

  event: content_block_delta
  data: {"type":"content_block_delta","index":0,"block_id":"block_example","delta":{"type":"text_delta","text":"Ticket volume decreased this week."}}

  event: message_stop
  data: {"type":"message_stop"}

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

## Validar un chat

<Accordion title="Parametros del endpoint">
  | Tipo | Nombre | Obligatorio | Notas |
  | - | - | - | - |
  | Body | `messages` | Si | Mensajes de solicitud de chat, enviados directamente en el nivel superior. No uses el envoltorio `pgpt` en este endpoint. Los campos opcionales de generacion, system y herramientas siguen el modelo de Messages enlazado. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/chat/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Give me a three-bullet summary of the Q1 support plan."
          }
        ]
      }
    ],
    "max_tokens": 64,
    "temperature": 0.3
  }'
```

Devuelve `200` con `valid: true`, o `400` con `valid: false` y el resultado de validacion. Los cuerpos invalidos o los fallos anteriores al resultado devuelven un error API estandar. Los campos nulos del resultado pueden omitirse. Esta operacion comprueba el cuerpo de Messages; el contexto de proyecto, las selecciones de artefactos y los permisos de Workspace se comprueban al ejecutar el chat.

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "valid": true,
    "request_summary": {
      "message_count": 1,
      "has_tools": false,
      "stream_enabled": false
    }
  }
  ```
</Accordion>

| Campo | Tipo | Significado |
| - | - | - |
| `valid` | boolean | Si la validacion fue correcta. |
| `errors` | string\[] o null | Errores de validacion. |
| `warnings` | string\[] o null | Avisos no fatales. |
| `request_summary` | object o null | Resumen opcional de la solicitud comprobada. |
| `request_summary.message_count` | integer o null | Numero de mensajes de entrada. |
| `request_summary.has_tools` | boolean o null | Si se enviaron herramientas. |
| `request_summary.stream_enabled` | boolean o null | Valor solicitado de stream. |
| `request_summary.tool_choice` | string o null | Modo solicitado de seleccion de herramientas. |

## Herramientas disponibles

Solo se aceptan herramientas definidas por Zylon en `pgpt.tools`; estas rutas de chat de Workspace no admiten herramientas personalizadas del cliente. Usa las [declaraciones y ejemplos de herramientas](/es/v1.58/developer-manual/build-with-zylon/tools/introduction-to-tools). Las herramientas de conocimiento de Workspace tambien incluyen `get_knowledge_base_files` (`list_files_v1`), `get_artifact_structure` (`get_file_structure_v1`), `get_artifact_content` (`get_content_v1`), `analyze_artifact` (`analyze_artifact_v1`), `summarize_artifact` (`summarize_artifact_v1`) y `create_document` (`process_content_v1`).

## Errores y casos límite

* **400**: esquema invalido, selectores de artefactos invalidos o solicitud sin exactamente un mensaje de usuario (usa `/chat/validate`).
* **403**: acceso al proyecto insuficiente o descargas deshabilitadas por la organizacion.
* Procesa los eventos SSE `error` y el evento final `done` despues de iniciar el stream HTTP.
* **404**: hilo o interacción no encontrada.
* **409**: interacción ya completada al cancelar.


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