Skip to main content
Chats in the Workspace API are organized around threads and interactions:
ConceptMeaning
ThreadA conversation container within a project.
InteractionA single exchange inside a thread.
ChatA one‑shot request that does not create a thread.
Use threads when you want history and follow‑ups. Use interactions to send a new turn into a thread. Use the chat endpoint for single‑turn requests.

​
Basic request and response

Create a thread interaction with 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"
}

​
Create or list threads

Create a new thread in a project: 
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"
  }'
List threads in a project: 
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
}

​
Update or delete a thread

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"
  }'
Delete a thread: 
curl -X DELETE "https://{BASE_URL}/api/v1/app/thread/{threadID}" \
  -H "Authorization: Bearer {API_TOKEN}"

​
List or fetch interactions

List interactions for a thread: 
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction?page=1&page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"
Fetch a specific interaction: 
curl "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
  -H "Authorization: Bearer {API_TOKEN}"

​
Delete or stream an interaction

Delete an interaction: 
curl -X DELETE "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
  -H "Authorization: Bearer {API_TOKEN}"
Stream interaction output: 
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"}

​
One‑shot chat

If you don’t need a thread, call the chat endpoint directly: 
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." }
  ]
}

​
Validate a chat request

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

​
Errors and edge cases

  • 400: invalid message schema (use /chat/validate).
  • 404: thread or interaction not found.
  • 409: interaction already completed when canceling.