> ## Documentation Index > Fetch the complete documentation index at: https://docs.closient.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an HRI preset > Save a new named HRI configuration at version 1, scoped to the caller's organization. 409 if the name is already taken by a non-archived preset in this organization. ## OpenAPI ````yaml /openapi/openapi-products.json post /products/api/v1/hri-presets/ openapi: 3.1.0 info: title: Products API version: 1.0.0 description: > Look up, claim, and browse GTINs in the Closient product repository. ## Authentication All endpoints require an API key passed via the `X-API-Key` HTTP header, unless otherwise noted. ``` X-API-Key: csb__ ``` Generate API keys in **Settings > API Keys** in your dashboard, or via the Account API. Session-based (cookie) authentication is also accepted for browser-based access. ## Rate Limits | Tier | Requests / minute | Requests / day | |-------------|-------------------|----------------| | Default | 300 | 10,000 | | Custom | Contact us | Contact us | Rate-limit headers are included on every response so callers can self-throttle without hitting our 429s ("informed governor"): - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400` - `RateLimit-Limit` — quota for the **most-restrictive** currently-active window - `RateLimit-Remaining` — requests left in that window - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew safe) Legacy `X-RateLimit-*` aliases are also emitted for back-compat. `X-RateLimit-Reset` keeps the absolute Unix-timestamp shape to avoid breaking existing consumers. When rate-limited, you receive `429 Too Many Requests` with a `retry_after_seconds` field in the error envelope and a `Retry-After` header. ## Pagination List endpoints return paginated results in this envelope: ```json { "data": [...], "pagination": { "page": 1, "page_size": 25, "total_count": 342, "total_pages": 14, "has_next": true, "has_previous": false } } ``` Use `?page=2&page_size=50` query parameters. Maximum page size is 100. ## Error Responses All errors conform to [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`: ```json { "type": "https://closient.com/docs/errors/not_found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found.", "error_code": "not_found", "retryable": false, "timestamp": "2026-03-31T12:00:00+00:00" } ``` Common error codes: `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_error` (422), `rate_limited` (429), `internal_error` (500). termsOfService: https://www.closient.com/terms/ servers: - url: https://www.closient.com security: [] tags: - name: Products description: Look up, claim, and browse products and trade items. - name: Product Group description: Manage GDSN packaging hierarchy relationships. - name: Import description: >- Bulk import products, batch/lots (GS1 AI 10) and serial numbers (GS1 AI 21) from CSV, TSV or XLSX files, with a downloadable template per entity. - name: QR description: Generate QR codes encoding GS1 Digital Link URLs. - name: Codes description: Generate GS1 DataMatrix and 1D barcodes (EAN/UPC/ITF-14/Code128). - name: Digital Link description: >- Parse GS1 Digital Link URIs into structured AIs (GTIN, lot, expiry, serial). - name: Labels description: >- Bulk label-export jobs: ZIPs of QR / DataMatrix / 1D symbols and multi-up sheet PDFs, async via Celery with status polling. - name: Lots description: >- Lot generator v2: format templates with persistent counters, reserve/commit/discard runs, soft/hard collision handling, and an async Celery path with SSE progress. - name: Retailer Catalog Import description: >- Server-side retailer catalog import jobs: stage normalised rows, then run the GTIN-keyed cross-retailer merge with a dry-run mode, per-field provenance and a quarantine report for every row refused. - name: HRI Presets description: >- Saved, named per-organisation Human Readable Interpretation (HRI) configurations — placement, layout, notation and typography. Referenceable by name from the QR generation endpoint, with an org default applied when no options or preset are supplied. - name: Product Links description: >- Generic, GS1-link-type-keyed brand CTA links (e.g. reviews, promotions, loyalty programs, homepage) attached to a product or a brand and rendered on the hosted page. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /products/api/v1/hri-presets/: post: tags: - HRI Presets summary: Create an HRI preset description: >- Save a new named HRI configuration at version 1, scoped to the caller's organization. 409 if the name is already taken by a non-archived preset in this organization. operationId: apps_products_api_hri_presets_create_hri_preset parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/HRIPresetCreateIn' required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/HRIPresetOut' '400': description: Bad Request content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '405': description: Method Not Allowed content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '409': description: Conflict content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '422': description: Unprocessable Content content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' security: - APIKeyHeaderAuth: [] - OAuthTokenAuth: [] - CookieGatedSessionAuth: [] components: schemas: HRIPresetCreateIn: description: Request body for `POST /hri-presets/`. examples: - is_default: true name: Retail house style - name: POS scan-critical options: notation: bracketed_ai pos_profile: true properties: name: description: Human-readable preset name. maxLength: 128 minLength: 1 title: Name type: string options: allOf: - $ref: '#/components/schemas/HRIOptions' description: >- The HRI configuration to save. Omit for the spec-preferred default configuration. is_default: default: false description: >- Make this the organization's default preset, applied when generation requests supply neither options nor a preset name. title: Is Default type: boolean required: - name title: HRIPresetCreateIn type: object HRIPresetOut: description: A saved HRI configuration. examples: - created: '2026-08-01T10:00:00Z' id: AbCdEfGhIjKlMnOpQrStUv is_archived: false is_default: true modified: '2026-08-01T10:00:00Z' name: Retail house style options: enabled: true layout: single_line notation: bracketed_ai placement: below pos_profile: false typography: alignment: center font_family: OCR-B font_size: 24 leading: 1.2 version: 1 properties: id: description: Preset id (22-char shortuuid). Use in `/hri-presets/{id}/` paths. title: Id type: string name: description: >- Human-readable preset name, unique among the org's non-archived presets. title: Name type: string options: $ref: '#/components/schemas/HRIOptions' description: The saved HRI configuration — the same model the API accepts inline. is_default: description: >- Applied by generation endpoints when no HRI options or named preset are supplied. title: Is Default type: boolean version: description: Bumps whenever `options` changes. title: Version type: integer is_archived: description: Archived presets are hidden from selection but keep their history. title: Is Archived type: boolean created: description: Creation timestamp (ISO-8601). format: date-time title: Created type: string modified: description: Last-modified timestamp (ISO-8601). format: date-time title: Modified type: string required: - id - name - options - is_default - version - is_archived - created - modified title: HRIPresetOut type: object ErrorOut: description: |- RFC 9457 Problem Details response. All API errors are returned in this format with Content-Type: application/problem+json. examples: - detail: The requested resource was not found. error_code: not_found retryable: false status: 404 timestamp: '2026-03-31T12:00:00+00:00' title: Not Found type: https://closient.com/docs/errors/not_found - detail: Validation error. details: - loc: - body - name msg: Field required type: missing error_code: validation_error retryable: false status: 422 timestamp: '2026-03-31T12:00:00+00:00' title: Validation Error type: https://closient.com/docs/errors/validation_error - detail: Rate limit exceeded. Please try again later. error_code: rate_limited retry_after: 31 retryable: true status: 429 timestamp: '2026-03-31T12:00:00+00:00' title: Rate Limited type: https://closient.com/docs/errors/rate_limited properties: type: description: URI reference identifying the error type. title: Type type: string title: description: Short human-readable summary of the error. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation of this specific occurrence. title: Detail type: string error_code: description: Machine-readable error code (e.g. not_found, unauthorized). title: Error Code type: string retryable: default: false description: Whether retrying the same request can succeed. title: Retryable type: boolean timestamp: description: ISO 8601 timestamp of when the error occurred. title: Timestamp type: string retry_after: anyOf: - type: integer - type: 'null' description: Seconds to wait before retrying (when applicable). title: Retry After owner_action_required: anyOf: - type: boolean - type: 'null' description: Whether the error requires account owner intervention. title: Owner Action Required details: description: Additional context (validation errors, etc.). title: Details required: - type - title - status - detail - error_code - timestamp title: ErrorOut type: object HRIOptions: allOf: - if: properties: layout: const: two_column required: - layout then: properties: notation: enum: - data_title - both required: - notation - if: properties: pos_profile: const: true required: - pos_profile then: properties: enabled: const: true notation: not: const: data_title description: |- Carrier-agnostic HRI configuration — the UI form, API and renderer's single source of truth (C-4389). Defaults produce the spec-preferred configuration with no user input: below the symbol, grouped together, bracketed-AI notation, OCR-B. Carrier- and element-sequence-aware checks (placement legality, the POS profile's structural requirement, character-set conformance) happen in :meth:`resolve`, not here — this model alone is what C-4395 persists as an organisation-level preset, before any specific carrier is chosen. examples: - enabled: true layout: single_line notation: bracketed_ai placement: below pos_profile: false typography: alignment: center font_family: OCR-B font_size: 24 leading: 1.2 properties: enabled: default: true description: >- Whether HRI is printed at all for this generated code. This is the model's 'None' placement choice (the epic's own 'HRI can be enabled or disabled per generated code' framing) — False disables HRI entirely rather than selecting a fifth placement value. title: Enabled type: boolean placement: allOf: - $ref: '#/components/schemas/HRIPlacement' default: below description: >- Where the HRI text block sits relative to the symbol. Below-grouped is the GenSpecs-preferred default. Legality is carrier-specific and is re-checked in resolve(), never here — this field alone does not know which carrier it will be rendered against. layout: allOf: - $ref: '#/components/schemas/HRILayout' default: single_line description: How multiple HRI elements are arranged within the text block. notation: allOf: - $ref: '#/components/schemas/HRINotation' default: bracketed_ai description: 'How each HRI element is printed: bracketed AI, data title, or both.' typography: allOf: - $ref: '#/components/schemas/HRITypography' description: Font, size, alignment and leading for the printed HRI text. pos_profile: default: false description: >- Pin AI (01) with the 14-digit GTIN as the first HRI element, for POS scanning. Structural requirements are validated against the actual element sequence in resolve(); this flag alone only fixes the notation/enabled combination it requires. title: Pos Profile type: boolean title: HRIOptions type: object HRIPlacement: description: |- Where the HRI text block sits relative to the symbol. GenSpecs 4.15 rule 1 clause c (quoted on the C-4386 epic): HRI SHOULD be placed below the symbol and grouped together wherever physically possible. ``BELOW`` is therefore the preferred placement for every carrier in this matrix; the other members exist for constrained layouts where a carrier's ``permitted_placements`` allows them. enum: - below - above - left - right examples: - below title: HRIPlacement type: string HRILayout: description: >- How the ordered HRI elements are arranged within the text block. ``SINGLE_LINE`` is this ticket's "single wrapped block" — GenSpecs 4.15 rule 1c's "grouped together" preference taken to its most literal reading, and this model's default (matching the pre-existing renderer default from C-4391, kept rather than renamed so no golden fixture or existing test changes). ``STACKED`` is one element per line. ``TWO_COLUMN`` prints the data title left-padded to a common column width, then the value — meaningful only when the notation actually carries a title (see :meth:`HRIOptions._validate_layout_notation_combo`). enum: - stacked - single_line - two_column examples: - single_line title: HRILayout type: string HRINotation: description: |- How each HRI element is printed. ``BRACKETED_AI`` — ``(01)09520123456788`` — GS1's own HRI convention and this model's default (spec-preferred, matches the pre-existing renderer default). ``DATA_TITLE`` — ``GTIN 09520123456788`` — the friendly-label form. ``BOTH`` combines them: ``(01) GTIN 09520123456788``. enum: - bracketed_ai - data_title - both examples: - bracketed_ai title: HRINotation type: string HRITypography: description: |- Font, size, alignment and leading for the printed HRI text. Defaults produce the spec-preferred configuration with no user input: OCR-B, the GenSpecs Rule 4 example font, at a size above the (provisional) legibility floor. ``font_size``'s default of 24.0 (C-4392) is deliberately well above the 8.0 provisional floor above: at the generator's own default retail X-dimension render (300 dpi / ~11.81 dots-per-mm, the fixed resolution ``qr_code.render_qr`` uses today), 14.0 units — this field's pre-C-4392 default — physically prints at roughly 1.2 mm, *below* the real 2 mm GenSpecs floor that ``apps.products.services.hri_legibility`` enforces at render time. 24.0 units clears 2 mm with a small margin (~2.03 mm) at that same resolution, so the epic's own "no user action required" default AC holds without every fresh page load presenting a legibility error. ``HRIStyle``'s own bare default stays 14.0 — unrelated call sites and the golden SVG conformance fixtures depend on that exact value; only this field's default changes. examples: - alignment: center font_family: OCR-B font_size: 24 leading: 1.2 properties: font_family: default: OCR-B description: >- CSS-style font-family value (may be a comma-separated fallback stack). OCR-B is the GenSpecs Rule 4 example and this field's default; any 'reasonable alternative font' is permitted provided legibility holds, but weight/width variant names (bold, italic, light, narrow, ...) are rejected outright. minLength: 1 title: Font Family type: string font_size: default: 24 description: >- Font size in the renderer's unitless coordinate space (see HRIStyle.font_size). minimum: 8 title: Font Size type: number alignment: allOf: - $ref: '#/components/schemas/HRIAlignment' default: center description: Text alignment within the HRI block. Not GenSpecs-constrained. leading: default: 1.2 description: >- Line-height multiple of font_size. Not GenSpecs-constrained; floor of 1.0 prevents overlapping lines. maximum: 2.5 minimum: 1 title: Leading type: number title: HRITypography type: object HRIAlignment: description: >- Text alignment within the HRI block. Not GenSpecs-constrained — a stylistic choice, unlike placement/layout/notation. Threaded into the renderer via :meth:`HRITypography.to_style` -> :attr:`HRIStyle.text_anchor` (C-4394). enum: - left - center - right examples: - center title: HRIAlignment type: string securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer CookieGatedSessionAuth: type: apiKey in: cookie name: sessionid ````