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

​
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 "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}"

{
  "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 "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}"

​
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}"
Obtener una interacción: 
curl "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
  -H "Authorization: Bearer {API_TOKEN}"

​
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}"
Streaming: 
curl -N "https://{BASE_URL}/api/v1/app/interaction/{interactionID}/stream" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -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 "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 "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
  }'

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