Doc: Resolves #12861: Add end point documentation for Transcribe (#12870)

Co-authored-by: Laurent Cozic <laurent22@users.noreply.github.com>

packages/transcribe/README.md

@@ -1,46 +1,138 @@
-# Installing
+# Installation and Setup
 
 ## Configure Docker for Transcribe
 
-1. Copy `.env-transcribe-sample` to the location of your Docker configuration files.
-2. Rename the file `.env-transcribe-sample` to `.env-transcribe`.
-3. `HTR_CLI_IMAGES_FOLDER` should be a full path to the folder that is going to store the images. It is an external folder, outside of the Docker container.
-4. Run the following command to test starting the server using the default configuration:
+1. Copy `.env-transcribe-sample` to your Docker configuration directory.
+2. Rename it to `.env-transcribe`.
+3. Set `HTR_CLI_IMAGES_FOLDER` to the full path of the folder where images will be stored. This folder must be outside the Docker container.
+4. Test the server with the default configuration:
 
 ```shell
 docker build -f ./Dockerfile.transcribe -t transcribe .
 docker run --env-file .env-transcribe -p 4567:4567 \
-     -v /var/run/docker.sock:/var/run/docker.sock \
-     -v ./packages/transcribe/images:/app/packages/transcribe/images \
-     transcribe
+	-v /var/run/docker.sock:/var/run/docker.sock \
+	-v ./packages/transcribe/images:/app/packages/transcribe/images \
+	transcribe
 ```
 
-## Using `docker compose`
+## Using Docker Compose
 
-For running with docker compose the minimal required configuration is available on `.env-sample` and `docker-compose.server.yml`.
+The minimal configuration is provided in `.env-sample` and `docker-compose.server.yml`.
 
 1. Run `cp .env-sample .env`
-2. Modify the options that make sense to you in the new `.env` file
-3. Run `docker compose -f docker-compose.server.yml --profile full up --detached`
+2. Update any options you need in `.env`
+3. Start the server:
 
-For further customization look at `.env-sample-transcribe`
+   ```shell
+   docker compose -f docker-compose.server.yml --profile full up --detached
+   ```
 
-# Setup for development
+For advanced configuration, refer to `.env-sample-transcribe`.
+
+---
+
+# Development Setup
 
 ## Testing
 
-The integration tests that require the full model to run **don't run by default, including on CI**. It is necessary to be extra careful when changing the model or the prompt because of that. The specific test that has been disabled is at `workers/JobProcessor.test.ts`
+Integration tests requiring the full model **do not run by default (including on CI)**. Be cautious when modifying the model or prompts.
+The disabled test is located at: `workers/JobProcessor.test.ts`.
 
-To run all tests, use the command:
+Run all tests with:
 
-```
+```shell
 yarn test-all
 ```
 
-## Setup up the database
+## Database Setup
 
-As the queue driver, we have the option of using SQLite or PostgreSQL, `QUEUE_DRIVER` can be set to `pg` or `sqlite` and `QUEUE_DATABASE_NAME` is the location of the SQLite file when using this configuration.
+The queue driver can be **SQLite** or **PostgreSQL**:
 
-## Starting the server
+* Set `QUEUE_DRIVER` to `sqlite` or `pg`.
+* If using SQLite, `QUEUE_DATABASE_NAME` specifies the path to the database file.
 
-From `packages/transcribe`, run `npm run start`
+## Starting the Server
+
+From `packages/transcribe`, run:
+
+```shell
+npm run start
+```
+
+---
+
+# API Endpoints
+
+All requests must include the `Authorization` header with the value set to your `API_KEY`.
+
+## POST `/transcribe`
+
+Creates a transcription job. The uploaded image is resized, stored on disk, and assigned to a job record in the database.
+
+**Request Body:**
+
+* **Content-Type**: `multipart/form-data`
+* **Field**: `file` (required) – the image file to process
+
+**Response:**
+
+```json
+{
+	"jobId": "bcd2e633-eb10-44cb-a280-bf723238c12e"
+}
+```
+
+**Example (cURL):**
+
+```shell
+curl --request POST \
+	--url http://localhost:4567/transcribe \
+	--header 'Authorization: api-key' \
+	--header 'Content-Type: multipart/form-data' \
+	--form file=@/home/js/Pictures/2025-07-24_17-42_1.png
+```
+
+---
+
+## GET `/transcribe/{jobId}`
+
+Fetches the result of a transcription job created with `POST /transcribe`.
+
+**Request:**
+
+* Requires a valid `jobId`.
+
+**Example Responses:**
+
+```json
+{
+	"id": "57ebd2e2-b496-40ab-9008-5f861bcb7858",
+	"state": "created"
+}
+```
+
+```json
+{
+	"id": "07f09553-f5e9-467e-b98d-406778e61969",
+	"state": "active"
+}
+```
+
+```json
+{
+	"id": "57ebd2e2-b496-40ab-9008-5f861bcb7858",
+	"completedOn": "2025-06-11T18:20:22.000Z",
+	"output": {
+		"result": "markdown\r\n# Main title\r\n\r\nSome text here. This should take more than one line.\r\n\r\n## Sub title\r\n\r\n- One kind\r\n  - of list\r\n    - sub-item\r\n\r\n## Conclusion\r\n\r\nLet's finish here."
+	},
+	"state": "completed"
+}
+```
+
+**Example (cURL):**
+
+```shell
+curl --request GET \
+	--url http://localhost:4567/transcribe/57ebd2e2-b496-40ab-9008-5f861bcb7858 \
+	--header 'Authorization: api-key'
+```