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

> Threads, interactions, and one-shot chat endpoints.

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

```bash theme={null}
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
    }
  }'
```

<Accordion title="Example response (InteractionDTO)">
  ```json theme={null}
  {
    "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"
  }
  ```
</Accordion>

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

<Accordion title="Example content blocks">
  ```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": "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%" }
      ]
    }
  ]
  ```
</Accordion>

Example interaction request with image + text and runtime flags:

```bash theme={null}
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:

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

List threads in a project:

```bash theme={null}
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}"
```

<Accordion title="Example response (schema not defined in OpenAPI)">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

## Update or delete a thread

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

Delete a thread:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

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

Stream interaction output:

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

<Accordion title="Example stream">
  ```text theme={null}
  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"}
  ```
</Accordion>

## One‑shot chat

If you don’t need a thread, call the chat endpoint directly:

```bash theme={null}
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
  }'
```

<Accordion title="Example response (schema not defined in OpenAPI)">
  ```json theme={null}
  {
    "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." }
    ]
  }
  ```
</Accordion>

## Validate a chat request

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

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