Chatbot REST API

Postman Collection Reference speech_to_text HTTP / multipart form-data

1. Overview

This document describes the REST endpoints from the speech_to_text Postman collection targeting the Pezhvak AI service. These endpoints cover speech-to-text, text-to-speech, chatbot dialog, knowledge learning, and text chat.

All requests in this collection use POST with multipart/form-data bodies.

Audio pipeline

Transcribe (file upload)
Transcribe via MinIO
Dialog (audio → response)
Dialog via MinIO

Text pipeline

Read / TTS
Read via MinIO
Learn (ingest URLs)
Chat (query → answer)

Relation to WebSocket protocol

These REST endpoints are a separate surface from the realtime WebSocket chat protocol (/ws/chat/{chatbot_id}/{client_id}/). Use this collection for non-streaming, request/response integrations (e.g. batch STT, TTS, knowledge ingest, one-shot chat).

2. Base Configuration

Collection name: speech_to_text

Property	Value
Schema	`https://schema.getpostman.com/json/collection/v2.1.0/collection.json`
Default base URL	`https://ai.pezhvak.im`
Default bot ID	`60c0917a-bd94-4b62-8cf6-9d20de375da0`
Auth (collection)	No explicit auth — most requests set `noauth`
Body mode	`formdata` (multipart)

3. Collection Variables

Variable	Default value	Usage
`base_url`	`https://ai.pezhvak.im`	Host + port for all requests
`bot_id`	`60c0917a-bd94-4b62-8cf6-9d20de375da0`	Chatbot identifier in path

URL pattern used throughout:

/en/api/...

Environment note

The sample host is an internal IP. Replace base_url with the production or staging host (e.g. https://ai.pezhvak.im) when deploying outside the lab network. Path prefix is /en/api/ (English locale); the WebSocket frontend used /fa/api/.

4. Endpoint Index

Name	Method	Path	Tags
Transcribe	`POST`	`/en/api/transcribe/`	audio · file
Transcribe (MinIO)	`POST`	`/en/api/transcribe-io/`	audio · minio
Dialog	`POST`	`/en/api/chatbot//dialog/`	audio · chat · file
Dialog (MinIO)	`POST`	`/en/api/chatbot//dialog-io/`	audio · chat · minio
Read (TTS)	`POST`	`/en/api/read/`	text · tts
Read (MinIO)	`POST`	`/en/api/read-io/`	text · tts · minio
Learn	`POST`	`/en/api/chatbot//learn/`	learn · urls
Chat	`POST`	`/en/api/chatbot//chat/`	chat · text

5. Transcribe

ai.pezhvak.im-transcribe

Upload an audio file and receive a transcription.

audio stt

POST /en/api/transcribe/

Body (form-data)

Key	Type	Required	Description
`audio`	file	yes	Audio file to transcribe (e.g. WAV, WebM)

Example (cURL)

curl -X POST "/en/api/transcribe/" \
  -F "audio=@recording.wav"

6. Transcribe (MinIO)

ai.pezhvak.im-minio-transcribe

Transcribe an audio object already stored in MinIO / object storage by filename. Avoids re-uploading the binary over the API.

audio minio stt

POST /en/api/transcribe-io/

Body (form-data)

Key	Type	Required	Example
`filename`	text	yes	`ab08d90e-5274-48e5-827c-7e57382622be.wav`

Example (cURL)

curl -X POST "/en/api/transcribe-io/" \
  -F "filename=ab08d90e-5274-48e5-827c-7e57382622be.wav"

7. Dialog

ai.pezhvak.im-dialog

Send an audio file to a specific chatbot. The server performs STT and returns a dialog / chatbot response (request/response, not streaming).

audio chat

POST /en/api/chatbot//dialog/

Path parameters

Param	Source	Description
`bot_id`	collection variable	Chatbot UUID

Body (form-data)

Key	Type	Required	Description
`audio`	file	yes	Audio utterance for the chatbot

Example (cURL)

curl -X POST "/en/api/chatbot//dialog/" \
  -F "audio=@utterance.wav"

8. Dialog (MinIO)

ai.pezhvak.im-minio-dialog

Same as Dialog, but the audio is referenced by MinIO object filename instead of uploading the file in the request body.

audio chat minio

POST /en/api/chatbot//dialog-io/

Body (form-data)

Key	Type	Required	Example
`filename`	text	yes	`ab08d90e-5274-48e5-827c-7e57382622be.wav`

Example (cURL)

curl -X POST "/en/api/chatbot//dialog-io/" \
  -F "filename=ab08d90e-5274-48e5-827c-7e57382622be.wav"

9. Read (Text-to-Speech)

ai.pezhvak.im-read

Convert text to speech. Send plain text; the server returns audio (exact response format is determined by the backend).

text tts

POST /en/api/read/

Body (form-data)

Key	Type	Required	Example
`text`	text	yes	`سلام، حالتون خوبه؟ چه خبرا؟`

Example (cURL)

curl -X POST "/en/api/read/" \
  -F "text=سلام، حالتون خوبه؟ چه خبرا؟"

10. Read (MinIO)

ai.pezhvak.im-minio-read

Text-to-speech variant that works with the MinIO / object-storage pipeline. Body is still text; storage of the resulting audio is handled server-side via MinIO.

text tts minio

POST /en/api/read-io/

Body (form-data)

Key	Type	Required	Description
`text`	text	yes	Long-form Persian text for TTS (sample in collection is a formal letter)

Example (cURL)

curl -X POST "/en/api/read-io/" \
  -F "text=با سلام و احترام، به استحضار میرساند..."

11. Learn

ai.pezhvak.im-learn

Ingest knowledge into a chatbot by providing a list of URLs (one per line). The backend crawls / indexes those pages for the given bot_id.

learn urls

POST /en/api/chatbot//learn/

Body (form-data)

Key	Type	Required	Description
`url`	text	yes	Newline-separated list of absolute URLs to learn from

Example value (truncated)

https://damavandco.com
https://damavandco.com/مرکز-تماس/
https://damavandco.com/help-desk/
https://damavandco.com/crm/
...

Example (cURL)

curl -X POST "/en/api/chatbot//learn/" \
  -F "url=https://example.com
https://example.com/about
https://example.com/faq"

12. Chat

ai.pezhvak.im-chat

One-shot text chat against a chatbot. Send a query string; receive a full answer (non-streaming, request/response).

chat text

POST /en/api/chatbot//chat/

Body (form-data)

Key	Type	Required	Example
`query`	text	yes	`نرم افزار مرکز تماس دماوند نسبت به برنامه های مشابه چه مزیت هایی دارد؟`

Example (cURL)

curl -X POST "/en/api/chatbot//chat/" \
  -F "query=نرم افزار مرکز تماس دماوند نسبت به برنامه های مشابه چه مزیت هایی دارد؟"

13. Request Patterns

Two recurring patterns appear across the collection:

A. Direct file upload

Binary audio is sent as a multipart file field:

POST /en/api/transcribe/          →  form field: audio (file)
POST /en/api/chatbot/{id}/dialog/ →  form field: audio (file)

B. MinIO / object reference

Instead of uploading bytes, the client passes a storage object name:

POST /en/api/transcribe-io/              →  form field: filename (text)
POST /en/api/chatbot/{id}/dialog-io/     →  form field: filename (text)

When to use MinIO variants

Use *-io endpoints when the audio is already in object storage (e.g. uploaded by another service or a previous step). This avoids transferring large binaries through the API gateway twice.

C. Text payloads

POST /en/api/read/                  →  form field: text
POST /en/api/read-io/               →  form field: text
POST /en/api/chatbot/{id}/learn/    →  form field: url   (newline-separated)
POST /en/api/chatbot/{id}/chat/     →  form field: query

14. Content Types

Aspect	Value
Request body mode	`multipart/form-data`
File field name (audio)	`audio`
Object name field	`filename`
TTS text field	`text`
Chat query field	`query`
Learn URLs field	`url`
Path locale prefix	`/en/api/`

Response schemas

The Postman collection does not include saved example responses. Exact JSON/binary response shapes (status codes, field names, audio MIME types) must be confirmed against the live API or backend source.

15. Authentication Notes

Every request in the collection that specifies auth uses "type": "noauth". No API keys, Bearer tokens, or custom headers are defined in the exported collection.

If the server enforces auth (API key, JWT, session cookie), it is not visible in this collection.
Internal IP host may rely on network-level access control.
Production deployments may require additional headers — verify with the backend team.

16. Integration Checklist

A client is compatible with this collection if it can:

#	Requirement
1	Resolve and (or hardcode equivalents)
2	Send `POST` with `multipart/form-data`
3	Upload binary audio under form key `audio` for transcribe & dialog
4	Pass object names under form key `filename` for `*-io` endpoints
5	Send TTS text under form key `text`
6	Send chat questions under form key `query`
7	Send learn sources under form key `url` (newline-separated URLs)
8	Use path prefix `/en/api/` (or the locale required by the deployment)
9	Handle both file-upload and MinIO-reference flows where both exist
10	Confirm response formats against live API (not specified in collection)

17. Core Contract Summary

Base:  /en/api/

STT (upload):
  POST /transcribe/                    form: audio=<file>

STT (MinIO):
  POST /transcribe-io/                 form: filename=<object-name>

Dialog (upload):
  POST /chatbot/{bot_id}/dialog/       form: audio=<file>

Dialog (MinIO):
  POST /chatbot/{bot_id}/dialog-io/    form: filename=<object-name>

TTS:
  POST /read/                          form: text=<string>
  POST /read-io/                       form: text=<string>

Learn:
  POST /chatbot/{bot_id}/learn/        form: url=<newline-separated URLs>

Chat:
  POST /chatbot/{bot_id}/chat/         form: query=<string>

Sufficient for REST integration

This contract is enough to implement STT, TTS, one-shot dialog, knowledge ingest, and text chat from any language that can issue multipart POST requests. For realtime streaming chat, use the WebSocket protocol document instead.

Chatbot REST API · Derived from Postman collection speech_to_text · For external client implementers