assistant

POST `/v1/assistant/conversations/{conversationId}/messages`

Ask the assistant a question and get its answer.

Kimlik Doğrulama

Bearer token olarak bir API anahtarı gönderin. Anahtar tickets.reply iznine sahip olmalıdır; bu izne sahip olmayan bir anahtar 404 ile değil, 403 ile reddedilir.

Bu uç nokta hiçbir organizasyon kimliği almaz. Anahtarınız zaten ait olduğu organizasyonu tanımlar ve yanıt bu organizasyonla sınırlandırılır.

Dene

Köşeli parantez içindeki her şeyi kendi değerlerinizle ve anahtar yer tutucusunu panonuzdan bir anahtarla değiştirin.

curl -X POST https://api.zinndigital.com/v1/assistant/conversations/{conversationId}/messages \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "question": <string> }'

Oturum açtınız mı? Panonuzdaki API konsolu, gerçek organizasyon kimliğinizi ve kendi anahtarınızı otomatik olarak doldurur ve isteği canlı API üzerinde çalıştırarak gerçek yanıtı görmenizi sağlar. Bu uç noktayı API konsolunda açın

Ayrıntılar

Synchronous: one request, two persisted turns, and the answer in the response. ⛔ Not `202` with a poll — §2.16 forbids an interactive path behind a job queue, and a chat that answers on the next poll is not a chat. Expect several seconds. The answer is grounded in **published knowledge-base articles** and, when `site_id` names one of your own sites, that site's health as read from our monitoring database. It cannot see another tenant's data, an unpublished draft, or a staff internal note — those are excluded by what the engine fetches, not by asking the model. It **cannot act**: no tool on this path changes anything. A `503` is a refusal fit to show the customer, and its `error_code` distinguishes the reasons — `ASSISTANT_DAILY_LIMIT`, `ASSISTANT_DISABLED`, `ASSISTANT_FAILED`, `ASSISTANT_UNAVAILABLE`. ⭐ Four, not six: an empty or over-long question is refused by validation as a `422` before anything is spent, so its code never reaches this response. Requires `tickets.reply`.

Parametreler

Ad	Tür	Zorunlu	Ne olduğu
`conversationId (path)`	`Uuid`	Evet	The conversation's id.

İstek gövdesi

Ad	Tür	Zorunlu	Ne olduğu
`question`	`string`	Evet	The customer's question, in their own language. Longer than this is a paste, not a question, and an unbounded prompt is an unbounded bill — so it is a `422`.
`site_id`	`Uuid`	Hayır	Which of your sites this is about. ⛔ Validated against your own sites before anything is read — an id from a client is a request, not a fact.
`page_context`	`string`	Hayır	The screen you asked from, as a route path — e.g. `/sites/{siteId}/backups`. "Why is this failing?" asked on the backups screen and on the DNS screen are different questions, an…

Yanıt

Ad	Tür	Zorunlu	Ne olduğu
`id`	`Uuid`	Evet	UUIDv7 identifier — sortable by creation time (docs/02 §8).
`role`	`AssistantRole`	Evet	—
`text`	`string`	Evet	—
`cited_slugs`	`string[]`	Evet	Knowledge-base slugs the answer used, for `/kb/<slug>` links. ⭐ Always a subset of what the engine supplied — a slug the model invented is dropped, because a fabricated citation…
`needs_human`	`boolean`	Evet	The model's own statement that it could not answer from what it was given. Recorded from its structured output, never inferred from the prose. This is what the "open a ticket" p…
`created_at`	`string`	Evet	—

Bu uç noktanın dönderebileceği hatalar

401 · 403 · 404 · 422 · 429 · 503

POST /v1/assistant/conversations/{conversationId}/messages