---
title: "Start a chat with the Temps assistant."
method: POST
path: "/ai/assistant/conversations"
tags: ["AI Chat"]
---

# Start a chat with the Temps assistant.

`POST /ai/assistant/conversations`

## Request

- Base URL: `/api` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/ai/assistant/conversations`
- Auth: HTTP bearer

The assistant runs on the AI gateway (an OpenRouter key is enough), has no
sandbox, and acts with the calling user's own permissions: every tool call
is replayed through the real router with their auth, and every change is a
proposal the user confirms in the UI. When no provider is configured this
answers `409` with `setup_path`, so the client can onboard instead of
failing.

## Request body

- CreateAssistantConversationRequest
  - `ai_model` string, nullable: Model id to start with; defaults to the provider's default model.
  - `ai_provider` string, nullable: An AI-gateway provider id (`gateway_key:<id>`). Defaults to the active OpenRouter key, then to the instance default. Host harnesses are rejected: the assistant has no sandbox.
  - `project_id` integer, nullable: A project the chat is about. The assistant is told which it is, so it needs no searching to resolve "my app". It is a default, not a limit, and grants nothing: the chat still acts with the user's own permissions.

## Response `201`

Conversation created

- ConversationResponse
  - `active_turn_id` string, nullable
  - `ai_model` string, required
  - `ai_permission_mode` string, required
  - `ai_provider` string, required
  - `ai_thinking_level` string, nullable
  - `application_id` integer, nullable
  - `context_id` string, required
  - `context_type` string, required
  - `context_usage` ContextWindowUsageResponse
    - `estimated` boolean, required
    - `limit_tokens` integer, nullable
    - `model` string, nullable
    - `source` string, required
    - `updated_at` string, required
    - `used_tokens` integer, required
  - `created_at` string, required
  - `failure` ChatFailureResponse
    - `code` string, required
    - `detail` string, required
    - `retryable` boolean, required
    - `title` string, required
  - `focus_project_id` integer, nullable: The project an assistant chat was started about, if any.
  - `kind` string, required: `ai` (a conversation with an AI harness) or `terminal` (an interactive shell in the workspace sandbox). Fixed at creation.
  - `last_activity_at` string, required
  - `project_id` integer, nullable
  - `public_id` string, required
  - `status` string, required
  - `title` string, nullable
  - `turn_started_at` string, nullable
  - `turn_status` string, required: Server-authoritative lifecycle for the current/most recent turn.

## Other responses

- `400`: Provider is not an AI-gateway provider
- `401`: Unauthorized
- `403`: Insufficient permissions
- `409`: No AI provider is configured; the problem carries `setup_path`

## Changes

> 81 revisions in range; 1 not diffed.

- **2026-10-20** `79089e9f49ee`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gotempsh/apis/temps/changes/ai/assistant/conversations/post.md)

---

[API](https://skmtc.dev/gotempsh/apis/temps.md) · [All operations](https://skmtc.dev/gotempsh/apis/temps/llms.txt) · [OpenAPI document](https://skmtc.dev/gotempsh/apis/temps/revisions/ab6d5d19e930?raw)