Chats - Zylon

Chats in the Workspace API are organized around threads and interactions:

Concept	Meaning
Thread	A conversation container within a project.
Interaction	A single exchange inside a thread.
Chat	A 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 "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
    }
  }'

Example response (InteractionDTO)

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

Adding media to the chat

If the selected model supports multimodal input, you can send media in pgpt.messages[].content[] (the same request shape used by both thread interactions and one-shot chat). You can mix multiple content blocks in one message. Supported block types in the schema:

Type	Typical use	Required fields	Notes
`text`	Plain text prompt/input	none	Uses `text`; supports optional `citations` metadata.
`image`	Image attachment	`data`	`data` can be base64 or URL; optional `mime_type`.
`audio`	Audio attachment	`data`	`data` can be base64 or URL; optional `mime_type`.
`binary`	Generic binary payload	`data`, `mime_type`	Optional `filename`.
`file`	File/document content block	`content`	Optional `content_type`, `doc_metadata`.
`tool_use`	Tool call request	`id`, `name`, `input`	Internal/tool orchestration block.

start_timestamp, stop_timestamp, and _meta are optional on all blocks.

Example content blocks

[
  { "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%" }
    ]
  }
]

Example interaction request with image + text and runtime flags:

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: asks the model to include citation references when available.
thinking.enabled: enables deep thinking mode; responses can take longer but are typically better reasoned.

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 "x-org: {org_slug}" \
  -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}"
  -H "x-org: {org_slug}"

Example response (schema not defined in OpenAPI)

{
  "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 "x-org: {org_slug}" \
  -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}"
  -H "x-org: {org_slug}"

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}"
  -H "x-org: {org_slug}"

Fetch a specific interaction:

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

Delete or stream an interaction

Delete an interaction:

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

Stream interaction output:

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"

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

Example response (schema not defined in OpenAPI)

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

Available tools

Pass tools in pgpt.tools as { "name": "...", "type": "..." }.

Name	Type	What it does
`semantic_search`	`semantic_search_v1`	Searches indexed project/workspace knowledge by semantic similarity.
`file_sematic_search`	`file_semantic_search_v1`	Searches file-based content and attachments semantically.
`tabular_analysis`	`tabular_analysis_v1`	Analyzes tabular datasets and returns computed insights.
`database_query`	`database_query_v1`	Runs database lookups/queries through configured data sources.
`web_search`	`web_search_v1`	Performs web search for external/public information.
`web_extract`	`web_extract_v1`	Extracts structured text/content from URLs.
`list_project_files`	`list_project_files_v1`	Lists files in the current project for downstream tool usage.

Errors and edge cases

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

Documentation Index

​Basic request and response

​Adding media to the chat

​Create or list threads

​Update or delete a thread

​List or fetch interactions

​Delete or stream an interaction

​One‑shot chat

​Validate a chat request

​Available tools

​Errors and edge cases