--- updatedAt: 2026-06-17T08:53:04.000Z agentTools: projectIndex: https://developer.tiliter.com/llms.txt --- # Create Product Sample Create a product sample for a specific product. Products samples are in-situ images of customer products, used to assist mapping to existing archetypes or train new products for recognition. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Tiliter Recognition API", "version": "1.15.11", "x-logo": { "href": "https://www.tiliter.com/", "url": "/logo.svg", "altText": "Tiliter logo" } }, "servers": [ { "url": "https://recognition.services.tiliter.com/v1/15", "description": "Production Endpoint (v1.15 versioned URL)" } ], "paths": { "/products/{product_id}/samples": { "post": { "tags": [ "Products" ], "summary": "Create Product Sample", "description": "Create a product sample for a specific product.\nProducts samples are in-situ images of customer products, used to assist mapping to existing archetypes\nor train new products for recognition.", "operationId": "create_product_sample", "parameters": [ { "required": true, "schema": { "type": "string", "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-]+$", "title": "Product Id" }, "name": "product_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSampleRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSampleResponse" } } } }, "404": { "description": "Device not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "415": { "description": "Image Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Request Throttled - reduce request rate and retry" } } } } }, "components": { "schemas": { "BagTypeEnum": { "type": "string", "enum": [ "none", "plastic", "plastic_net", "paper" ], "title": "BagTypeEnum", "description": "An enumeration." }, "CameraType": { "type": "string", "enum": [ "generic", "MP7000-P", "MP7000-L", "7879e-C3", "TDI", "TC0", "TC1", "TC2", "SM6000", "9900I-TDR", "9600I-CCMV" ], "title": "CameraType", "description": "An enumeration." }, "ClientError": { "properties": { "message": { "type": "string", "title": "Message" }, "error_type": { "$ref": "#/components/schemas/ErrorType" }, "error_code": { "type": "integer", "title": "Error Code", "description": "HTTP status code for the error" } }, "type": "object", "required": [ "message", "error_type", "error_code" ], "title": "ClientError" }, "Currency": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STN", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW" ], "title": "Currency", "description": "ISO4217 code representing the Sale Currency: https://www.iso.org/iso-4217-currency-codes.html" }, "DepartmentType": { "type": "string", "enum": [ "no_product", "fresh_produce", "bulk_goods" ], "title": "DepartmentType", "description": "An enumeration." }, "ErrorType": { "type": "string", "enum": [ "already_exists", "does_not_exist", "bad_request", "internal_error", "unauthorized" ], "title": "ErrorType", "description": "An enumeration." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Image": { "properties": { "camera_type": { "$ref": "#/components/schemas/CameraType" }, "capture_time": { "type": "string", "format": "date-time", "title": "Capture Time", "description": "Time the image was captured, in ISO format" }, "image": { "type": "string", "minLength": 100, "pattern": "^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$", "title": "Image", "description": "Base64 encoded .png or .jpeg image" } }, "type": "object", "required": [ "camera_type", "capture_time", "image" ], "title": "Image", "description": "Models the data and MetaData around the image" }, "LargeProductQuantity": { "type": "string", "enum": [ "1", "2", "3" ], "title": "LargeProductQuantity", "description": "An enumeration." }, "MediumProductQuantity": { "type": "string", "enum": [ "1", "2", "3", "4" ], "title": "MediumProductQuantity", "description": "An enumeration." }, "ProductAttributes": { "type": "string", "enum": [ "in_paper_bag", "chiquita_marking", "organic_marking" ], "title": "ProductAttributes", "description": "An enumeration." }, "ProductInternal": { "properties": { "recognition_enabled": { "type": "boolean", "title": "Recognition Enabled", "description": "If true(default), this product will be recognised, set to false to have the product ignored", "default": true }, "product_id": { "type": "string", "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-]+$", "title": "Product Id", "description": "A unique identifier for the object", "example": "1a2312" }, "product_name": { "type": "string", "maxLength": 40, "minLength": 1, "title": "Product Name", "description": "The formal name of a Retailer Product. This will be included in the recognition response, and in reporting. It should be a human-friendly name and it is recommended to use the same wording in existing catalogues and marketing material." }, "product_description": { "type": "string", "maxLength": 500, "title": "Product Description", "description": "A description of the product which may be used in the recognition response and/or to assist mapping." }, "archetype_id": { "type": "string", "format": "uuid", "title": "Archetype Id", "description": "A unique identifier assigned to each Tiliter Archetype. It serves as a mapping key between Tiliter Archetypes and Products." }, "lookup_code": { "type": "string", "maxLength": 20, "pattern": "^(\\d*)$", "title": "Lookup Code", "description": "An alternative to the product ID field. Can correspond to a PLU (product lookup code) or UPC (universal product code).", "example": "1234" }, "department": { "allOf": [ { "$ref": "#/components/schemas/DepartmentType" } ], "description": "The department a product is in. Specifying a department a product is in allows for devices in one department to never receive products from another department." }, "required_attributes": { "items": { "$ref": "#/components/schemas/ProductAttributes" }, "type": "array", "uniqueItems": true, "description": "Use this field to specify essential attributes always present on a Retailer Product. For instance, if peanuts must be in a paper bag and cannot be sold loose, set the `in_paper_bag` attribute as required. The Tiliter Recognition API will only return peanuts if a paper bag is detected. Similarly, if a product is always identified by a marking on the item (for example a `chiquita_marking` branded sticker or an `organic_marking` label), set that marking attribute as required. The Tiliter Recognition API will only return the product if the marking is detected." }, "optional_attributes": { "items": { "$ref": "#/components/schemas/ProductAttributes" }, "type": "array", "uniqueItems": true, "description": "Use this field to specify optional attributes that may be present on a Retailer Product. For instance, if bananas may be organic or not organic, set the specialty label as an optional attribute. That way, the Tiliter Recognition API will know that bananas can be sold in both ways and provide responses accordingly." }, "sale_method": { "anyOf": [ { "$ref": "#/components/schemas/SellByQuantity" }, { "$ref": "#/components/schemas/SellByWeight" } ], "title": "Sale Method", "description": "Specifies the Retailer Product's selling method, either by weight or by quantity. Examples include selling bananas by weight and passionfruit by quantity." }, "image_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Image Url", "description": "The URL of an image representing the Retailer Product. This optional field specifies a secure HTTPS link to a product image, The image MIME type much be one of the following: image/jpeg, image/png, image/bmp, image/webp, or image/tiff." }, "archetype_name": { "type": "string", "title": "Archetype Name", "description": "The name of the archetype the product is mapped to" } }, "type": "object", "required": [ "product_id", "product_name", "department" ], "title": "ProductInternal", "description": "Includes mapping to archetype, this may be replaced with the DB model\nin the future" }, "ProductSampleRequest": { "properties": { "product": { "allOf": [ { "$ref": "#/components/schemas/ProductInternal" } ], "title": "Product", "description": "Product being sampled" }, "sample_type": { "allOf": [ { "$ref": "#/components/schemas/SampleType" } ], "description": "Type of sample being collected", "default": "test" }, "collector_email": { "type": "string", "title": "Collector Email", "description": "Email of the person who collected the sample" }, "camera_type": { "allOf": [ { "$ref": "#/components/schemas/CameraType" } ], "description": "Type of camera used to capture the sample" }, "background_type": { "allOf": [ { "$ref": "#/components/schemas/ScaleBackgroundType" } ], "description": "Type of background used to capture the sample" }, "bag_type": { "allOf": [ { "$ref": "#/components/schemas/BagTypeEnum" } ], "description": "Type of bag used to capture the sample" }, "product_size": { "allOf": [ { "$ref": "#/components/schemas/ProductSize" } ], "description": "Size of the product in the sample" }, "product_quantity": { "anyOf": [ { "$ref": "#/components/schemas/SmallProductQuantity" }, { "$ref": "#/components/schemas/MediumProductQuantity" }, { "$ref": "#/components/schemas/LargeProductQuantity" } ], "title": "Product Quantity", "description": "Quantity of the product in the sample" }, "device_id": { "type": "string", "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-]+$", "title": "Device Id", "description": "The Device that the image/s were captured on. This must match an existing device.", "example": "TV012303" }, "images": { "items": { "$ref": "#/components/schemas/Image" }, "type": "array", "maxItems": 2, "minItems": 1, "title": "Images", "description": "List of images containing the product to be recognized" }, "weight_grams": { "type": "number", "title": "Weight Grams", "description": "Weight in grams if available. Improves results", "example": 100.1 } }, "type": "object", "required": [ "device_id", "images" ], "title": "ProductSampleRequest", "description": "list of images containing the product to be recognized," }, "ProductSampleResponse": { "properties": { "sample_id": { "type": "string", "format": "uuid", "title": "Sample Id" }, "product_id": { "type": "string", "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-]+$", "title": "Product Id" } }, "type": "object", "required": [ "sample_id", "product_id" ], "title": "ProductSampleResponse" }, "ProductSize": { "type": "string", "enum": [ "small", "medium", "large" ], "title": "ProductSize", "description": "An enumeration." }, "QuantityUnit": { "type": "string", "enum": [ "ea", "bunch", "pack" ], "title": "QuantityUnit", "description": "An enumeration." }, "SampleType": { "type": "string", "enum": [ "test", "train" ], "title": "SampleType", "description": "An enumeration." }, "ScaleBackgroundType": { "type": "string", "enum": [ "unknown", "datalogic_9400i", "datalogic_9600i", "datalogic_9800i", "datalogic_9900i", "zebra_mp7", "tiliter_adt" ], "title": "ScaleBackgroundType", "description": "An enumeration." }, "SellByQuantity": { "properties": { "unit_price": { "type": "number", "exclusiveMinimum": true, "title": "Unit Price", "minimum": 0 }, "currency": { "$ref": "#/components/schemas/Currency" }, "quantity_unit": { "$ref": "#/components/schemas/QuantityUnit" } }, "type": "object", "required": [ "unit_price", "currency", "quantity_unit" ], "title": "SellByQuantity" }, "SellByWeight": { "properties": { "unit_price": { "type": "number", "exclusiveMinimum": true, "title": "Unit Price", "minimum": 0 }, "currency": { "$ref": "#/components/schemas/Currency" }, "weight_unit": { "$ref": "#/components/schemas/WeightUnit" }, "tare": { "type": "number", "title": "Tare", "description": "Tare in the weight_unit", "minimum": 0 } }, "type": "object", "required": [ "unit_price", "currency", "weight_unit", "tare" ], "title": "SellByWeight" }, "SmallProductQuantity": { "type": "string", "enum": [ "50g", "100g", "250g", "500g" ], "title": "SmallProductQuantity", "description": "An enumeration." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WeightUnit": { "type": "string", "enum": [ "kg", "g", "lb", "oz" ], "title": "WeightUnit", "description": "An enumeration." } }, "securitySchemes": { "api-key-auth": { "type": "apiKey", "name": "tiliter-api-key", "in": "header" } } }, "tags": [ { "name": "Products", "description": "To recognise products, two things are required to be configured with the Tiliter Recognition API:\n1. Products are registered with the Tiliter Recognition API\n2. Those products are mapped to Tiliter Archetypes\n\nThis section covers registering the Products. Mapping these Products to Tiliter Archetypes is covered in Product Mapping and Archetypes.\n\nRegistering a Retailer Product creates a virtual product, with the product name, ID, and other information that is important to the retailer. Products can be created, updated, and deleted using the functions provided.\n\nProduct Samples can be used to assist mapping process and improve recognition." } ], "security": [ { "api-key-auth": [] } ], "x-tagGroups": [ { "name": "Api Reference", "tags": [ "Products", "Product Mapping and Archetypes", "Devices", "Stores and Stock", "Recognise and Select" ] } ] } ```