> This page is for API Reference. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fiftytwo-demo.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fiftytwo-demo.ferndocs.com/_mcp/server. # Upload a new image POST https://api.fiftytwo.com/masterdata/images/v1/chain/{chain} Content-Type: multipart/form-data Uploads a single image file with optional quality setting. The image is processed and stored with an MD5 hash as its identifier. Content-based deduplication ensures that identical images are not stored multiple times per customer. Images are stored per customer but metadata is tracked per chain. **Important:** Only one file can be uploaded per request. Requests with multiple files will be rejected with a 400 BadRequest response. **Quality Options:** | Quality | Max Dimensions | Encoding Quality | Output Format | Use Case | | ---------- | -------------- | ---------------- | ------------- | ------------------------------- | | `original` | No resizing | 100% (lossless) | WebP | When exact original is needed | | `high` | 1024x1024 px | 90% | WebP | Product images, detailed photos | | `medium` | 512x512 px | 80% | WebP | Default, balanced quality/size | | `low` | 128x128 px | 60% | WebP | Thumbnails, low bandwidth | **Notes:** * Maximum file size: 10MB. Requests exceeding this will be rejected with a 400 BadRequest response. * All resizing maintains aspect ratio (images are scaled to fit within max dimensions) * WebP format provides better compression than JPEG while maintaining quality * Original quality preserves the image without any quality loss * Supported input formats: PNG, JPEG, WebP, GIF, BMP **Optional Associations (Two Approaches):** You can associate images with articles and viewgroups using either of these approaches: \*\*Approach 1: Query Parameters \*\* Simplest as it is not needed to store the imageId for subsequent calls \*\*Approach 2: Entity APIs * For Articles: Use POST /articles/v1/chain/\{chainId} with `images` array in the request body * Example: `"images": [{"imageId": "abc123", "isDefault": 1}]` * This updates the article entity with the image reference * For ViewGroups: Use POST /viewGroups/v1/chain/\{chainId} with `imageId` field in the request body * Example: `"imageId": "abc123"` * This updates the viewgroup entity with the image reference **Example Request:** ``` POST /images/v1/chain/1?quality=medium&articleId=1234567890123 Content-Type: multipart/form-data file: [binary image data] ``` **Response Headers:** * `Location` - URL to track the processing status (e.g., /BaseData/v1/id/\{baseDataId}) Reference: https://fiftytwo-demo.ferndocs.com/api/master-data/reference/images/upload-image ## Request ### Path parameters - `chain` (integer, required) — The ID of the chain ### Query parameters - `quality` (string, optional, default: medium) — Image quality setting: original, high, medium (default), or low - `articleId` (long, optional) — Optional: Associate this image with an article by providing the articleId - `viewGroupId` (long, optional) — Optional: Associate this image with a viewgroup by providing the viewGroupId ### Body (multipart/form-data) This endpoint expects a multipart form containing a file. - `file` (file, required) — Image file to upload (PNG, JPEG, WebP, GIF, BMP; max 10MB) ## Response ### 201 Image uploaded successfully. Response body contains image metadata and Location header points to status tracking endpoint. ## Errors ### 400 Bad Request Error Invalid file format, missing file, or multiple files detected - `string` ## Examples **Request** ```json { "file": "" } ``` **Response** ```json { "contentType": "image/webp", "height": 600, "imageId": "7af0a3950a162be27488d0c1f292f9ab", "originalFileName": "product-photo.jpg", "quality": "medium", "size": 2048, "uploadedAt": "2025-01-15T10:30:00Z", "width": 800 } ``` **SDK Code** ```python Images_UploadImage_example import requests url = "https://api.fiftytwo.com/masterdata/images/v1/chain/1" files = { "file": "open('string', 'rb')" } response = requests.post(url, files=files) print(response.json()) ``` ```javascript Images_UploadImage_example const url = 'https://api.fiftytwo.com/masterdata/images/v1/chain/1'; const form = new FormData(); form.append('file', 'string'); const options = {method: 'POST'}; options.body = form; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Images_UploadImage_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.fiftytwo.com/masterdata/images/v1/chain/1" payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n") req, _ := http.NewRequest("POST", url, payload) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Images_UploadImage_example require 'uri' require 'net/http' url = URI("https://api.fiftytwo.com/masterdata/images/v1/chain/1") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n" response = http.request(request) puts response.read_body ``` ```java Images_UploadImage_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.fiftytwo.com/masterdata/images/v1/chain/1") .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n") .asString(); ``` ```php Images_UploadImage_example request('POST', 'https://api.fiftytwo.com/masterdata/images/v1/chain/1', [ 'multipart' => [ [ 'name' => 'file', 'filename' => 'string', 'contents' => null ] ] ]); echo $response->getBody(); ``` ```csharp Images_UploadImage_example using RestSharp; var client = new RestClient("https://api.fiftytwo.com/masterdata/images/v1/chain/1"); var request = new RestRequest(Method.POST); request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Images_UploadImage_example import Foundation let parameters = [ [ "name": "file", "fileName": "string" ] ] let boundary = "---011000010111000001101001" var body = "" var error: NSError? = nil for param in parameters { let paramName = param["name"]! body += "--\(boundary)\r\n" body += "Content-Disposition:form-data; name=\"\(paramName)\"" if let filename = param["fileName"] { let contentType = param["content-type"]! let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8) if (error != nil) { print(error as Any) } body += "; filename=\"\(filename)\"\r\n" body += "Content-Type: \(contentType)\r\n\r\n" body += fileContent } else if let paramValue = param["value"] { body += "\r\n\r\n\(paramValue)" } } let request = NSMutableURLRequest(url: NSURL(string: "https://api.fiftytwo.com/masterdata/images/v1/chain/1")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```