Saltar al contenido principal
Los chats en la Workspace API se organizan alrededor de hilos e interacciones:
ConceptoSignificado
ThreadContenedor de conversación dentro de un proyecto.
InteractionInteracción individual dentro del hilo.
ChatSolicitud 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.

​
Solicitud básica y respuesta

Crea una interacción en un hilo con POST /api/v1/app/thread/{threadId}/interaction. 
curl -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" \
  -d '{
    "thread_id": "{threadID}",
    "artifact_ids": ["{artifactID}"],
    "all_artifacts": false,
    "agent": "Default",
    "pgpt": {
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "Summarize the artifact in three bullets." }
          ]
        }
      ],
      "max_tokens": 120,
      "temperature": 0.2
    }
  }'

{
  "id": "inter_5a7b9c1d3e5f7a9b",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "thread_id": "thread_3f2a1c4d5b6e7f8a",
  "state": "Completed",
  "artifact_ids": ["artifact_2b4d6f8a1c3e5a7b"],
  "all_artifacts": false,
  "user_input": {
    "role": "user",
    "content": [
      { "type": "text", "text": "Summarize the artifact in three bullets." }
    ]
  },
  "assistant_output": {
    "id": "msg_3d2c1b4a5f6e7d8c",
    "created": 1739036500,
    "model": "default",
    "stop_reason": "end_turn",
    "content": [
      { "type": "text", "text": "• Ticket volume rose 12% week-over-week\n• Billing issues drove 38% of cases\n• Priority bugs were resolved within 48 hours" }
    ],
    "usage": { "input_tokens": 180, "output_tokens": 52 }
  },
  "created_at": "2026-02-08T14:41:10Z"
}

​
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:
TipoUso típicoCampos requeridosNotas
textPrompt/entrada en texto planoningunoUsa text; soporta metadata opcional de citations.
imageImagen adjuntadatadata puede ser base64 o URL; mime_type es opcional.
audioAudio adjuntodatadata puede ser base64 o URL; mime_type es opcional.
binaryPayload binario genéricodata, mime_typefilename opcional.
fileBloque de archivo/documentocontentcontent_type y doc_metadata opcionales.
tool_useSolicitud de llamada de herramientaid, name, inputBloque interno de orquestación de tools.
start_timestamp, stop_timestamp y _meta son opcionales en todos los bloques. 
[
  { "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": "tool_use", "id": "toolu_123", "name": "semantic_search", "input": { "query": "billing issues" } },
  {
    "type": "tool_result",
    "tool_use_id": "toolu_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%" }
    ]
  }
]
Ejemplo de interacción con imagen + texto y flags de ejecución: 
curl -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" \
  -d '{
    "thread_id": "{threadID}",
    "all_artifacts": true,
    "artifact_ids": [],
    "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: 
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: 
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/thread?page=1&page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"

{
  "data": [
    {
      "id": "thread_3f2a1c4d5b6e7f8a",
      "name": "Weekly Support Brief",
      "visibility": "Private",
      "created_at": "2026-02-08T14:40:00Z"
    }
  ],
  "has_next_page": false,
  "has_previous_page": false,
  "total_count": 1
}

​
Actualizar o eliminar un hilo

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: 
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: 
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction?page=1&page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
Obtener una interacción: 
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

Eliminar una interacción: 
curl -X DELETE "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
Streaming: 
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"

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

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"• Ticket volume rose 12%"}}

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

​
Chat de una sola llamada

Si no necesitas un hilo, usa el endpoint de chat: 
curl -X POST "https://{BASE_URL}/api/v1/app/chat" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Draft a 2-sentence update on this week’s support backlog." }
        ]
      }
    ],
    "max_tokens": 64,
    "temperature": 0.3
  }'

{
  "id": "msg_5f2e1d3c4b6a7c8d",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Backlog volume dipped 8% this week after closing high-priority billing cases. We’ll focus next on resolving long-tail authentication issues." }
  ]
}

​
Validar una solicitud de chat

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

​
Herramientas disponibles

Pasa tools en pgpt.tools como { "name": "...", "type": "..." }.
NombreTipoQué hace
semantic_searchsemantic_search_v1Busca conocimiento indexado del proyecto/workspace por similitud semántica.
file_sematic_searchfile_semantic_search_v1Busca semánticamente en archivos y adjuntos.
tabular_analysistabular_analysis_v1Analiza datasets tabulares y devuelve insights calculados.
database_querydatabase_query_v1Ejecuta consultas a bases de datos configuradas.
web_searchweb_search_v1Realiza búsqueda web para información externa/pública.
web_extractweb_extract_v1Extrae contenido estructurado de URLs.
list_project_fileslist_project_files_v1Lista archivos del proyecto actual para usarlos con otras tools.

​
Errores y casos límite

  • 400: esquema inválido (usa /chat/validate).
  • 404: hilo o interacción no encontrada.
  • 409: interacción ya completada al cancelar.