---
title: "Create Workspace Chat"
method: POST
path: "/api/comms/{team_key}/workspace/"
tags: ["comms"]
---

# Create Workspace Chat

`POST /api/comms/{team_key}/workspace/`

## Request

- Base URL: `https://api.superit.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.superit.ai/api/comms/{team_key}/workspace/`
- Auth: HTTP bearer

Create a new workspace chat.

This endpoint is used when a user sends their first message from the
empty workspace chat state. It creates the chat shell and persists a
goal SystemTurn synchronously — the first user message arrives later
via the WebSocket (which itself emits a
``ChatTurnIntent(ChatKey, USER)``).

Chat-shell creation is a first-class operation distinct from "advance
a chat by one turn": there is no turn to persist here, so we call
``get_or_create_chat_shell`` directly rather than constructing a
placeholder ``Turn`` just to satisfy ``ChatTurnIntent``'s shape.
Dedup + principal validation still share the same
``_create_chat_with_dedup`` codepath as the turn-driven flows.

The goal SystemTurn is persisted in-route (not emitted as a
``ChatTurnIntent``) so the goal row is guaranteed to exist before
the user's first WebSocket message can be processed — otherwise the
runner's history-fold may run without the goal in
``build_system_prompt`` on the first reply.

## Path parameters

- `team_key` string, required

## Request body

- CreateWorkspaceChatRequest: Request body for creating a new workspace chat.
  - `source` 'querystring' | 'direct'
  - `ticket` TicketContextInput: Ticket context for chat creation.
    - `key` string, required
    - `summary` string, required
    - `status` string, required
    - `source` string
    - `updated_at` string, nullable
  - `agent_id` string, nullable
  - `onboarding` boolean
  - `step` 'install_agent' | 'connect_psa' | 'setup_managed_team' | 'setup_ticket_automation': The four checklist steps, in the order the card and Sparky present them.

## Response `201`

Successful Response

- CreateWorkspaceChatResponse: Response for successful chat creation.
  - `chat_key` string, required
  - `ticket_key` string, nullable
  - `resumed` boolean

## Other responses

- `400`: Invalid input
- `401`: Not authenticated
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: Conflict
- `422`: Validation Error

---

[API](https://skmtc.dev/superit/apis/super-it-api.md) - [All operations](https://skmtc.dev/superit/apis/super-it-api/llms.txt) - [OpenAPI document](https://skmtc.dev/superit/apis/super-it-api/revisions/4944d556c2bb?raw)