Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/floriansalvi/HEIG-VD_Ocha-api/llms.txt

Use this file to discover all available pages before exploring further.

The Ocha API provides a dedicated endpoint for uploading or replacing a product’s image. You send the image as a base64-encoded string or a public URL in a JSON request body. The value is passed directly to Cloudinary, which resizes and optimises it, and the resulting secure URL is saved to the product’s image field. Only administrators can use this endpoint.

​
Endpoint

PUT /api/v1/products/:id/image
DetailValue
MethodPUT
AuthenticationRequired — Bearer JWT (admin role)
Content-Typeapplication/json
Body field nameimage

​
How it works

1

Authenticate as an admin

Obtain a JWT token by logging in with an admin account via POST /api/v1/auth/login. Include the token as a Bearer token in the Authorization header of the upload request.
2

Prepare your image source

The image field accepts any value that Cloudinary’s uploader accepts — a base64 data URI (e.g. data:image/jpeg;base64,...) or a publicly accessible image URL. Common formats such as JPEG and PNG are accepted. Cloudinary will resize it to 500×500 with fill cropping and auto gravity.
3

Send the JSON request

Send a PUT request with Content-Type: application/json and a body containing the image field.
4

Verify the response

A 200 OK response includes the Cloudinary-hosted URL in imageUrl. The product’s image field is also updated in the database.

​
curl example

curl -X PUT "https://api.example.com/api/v1/products/64f1c2e9a1b2c3d4e5f12345/image" \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/path/to/matcha-latte.jpg"}'

​
Success response

{
  "message": "Image uploaded successfully",
  "imageUrl": "https://res.cloudinary.com/your-cloud/image/upload/f_auto,q_auto/products/matcha-latte.webp"
}

​
Cloudinary processing

When an image is uploaded, Cloudinary applies the following transformations before storing it:
SettingValue
Width500 px
Height500 px
Crop modefill
Gravityauto
Formatauto (served as WebP where supported)
Qualityauto
Folderproducts/
Public IDProduct’s slug
Overwritetrue
Uploading a new image for a product that already has one will overwrite the existing Cloudinary asset because the public ID is derived from the product’s slug and overwrite is set to true.

​
Error responses

StatusMeaning
400The image field is missing from the request body, or the ID format is invalid
401No token provided, the token is invalid, or it has expired
403The authenticated user does not have the admin role
404No product exists with the given :id
500An unexpected server or Cloudinary error occurred
A 401 response means the request was not authenticated at all — either the Authorization header is absent or the token is malformed or expired. A 403 response means the token is valid but belongs to a non-admin user.

​
Next steps

Create a product

Create a product before uploading its image.

Upload image API reference

Full API reference for the image upload endpoint.

Roles and permissions

Learn about admin-only endpoints and how authentication works.

Environment variables

Configure CLOUDINARY_URL and other required environment variables.

Build docs developers (and LLMs) love

Get started for freeTalk to us