> ## 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. # Get full product detail by GTIN > Returns comprehensive product information including substance composition, certifications, and claims for a given GTIN. Accepts GTIN-8, GTIN-12, GTIN-13, or GTIN-14 formats. ## OpenAPI ````yaml /openapi/openapi-agent.json get /agent/api/v1/products/{gtin} openapi: 3.1.0 info: title: Agentic Commerce API version: 1.0.0 description: > Structured API for AI shopping assistants (ChatGPT, Gemini, Perplexity) to resolve product availability at nearby stores via tool use. Accepts natural-language product queries with geographic context and returns ranked results with real-time store availability. ## 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: Resolve description: Resolve product queries to nearby store availability. - name: Products description: Retrieve detailed product information by GTIN. - name: Availability description: Check store availability for a known product. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /agent/api/v1/products/{gtin}: get: tags: - Products summary: Get full product detail by GTIN description: >- Returns comprehensive product information including substance composition, certifications, and claims for a given GTIN. Accepts GTIN-8, GTIN-12, GTIN-13, or GTIN-14 formats. operationId: apps_agent_api_product_product_detail parameters: - in: path name: gtin schema: description: >- GTIN of the product to look up. Accepts GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN-13), or GTIN-14; the service pads shorter forms to GTIN-14 internally before lookup. maxLength: 14 minLength: 8 pattern: ^\d{8}$|^\d{12,14}$ title: Gtin type: string required: true description: >- GTIN of the product to look up. Accepts GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN-13), or GTIN-14; the service pads shorter forms to GTIN-14 internally before lookup. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ProductDetailOut' '400': description: Bad Request 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' '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: ProductDetailOut: description: |- Full product detail with substances, certifications, and claims. Returned by ``GET /products/{gtin}``. Heavier than :class:`ProductOut` — includes typed certification / claim / substance detail rather than label-only summaries, so an assistant can reason about validity, sources, and ingredient composition without a follow-up call. examples: - brand: Acme Beverages category: Food, Beverages & Tobacco > Beverages > Milk certifications: - issuing_body: USDA label: USDA Organic valid_from: '2024-01-01' valid_until: '2026-01-01' verification_status: verified claims: - label: Vegan source: THIRD_PARTY_VERIFIED valid: true country_of_origin: US description: Creamy organic almond milk, unsweetened. gtin: '00012345678905' image_url: https://cdn.closient.com/products/00012345678905/hero.jpg name: Organic Almond Milk net_content: 500ml substances: - is_major_allergen: true may_contain: false name: Almonds percentage: 15 type: FOOD_INGREDIENT properties: gtin: description: GTIN-14 identifier (always 14 digits, zero-padded). maxLength: 14 minLength: 14 pattern: ^\d{14}$ title: Gtin type: string name: description: Product name. title: Name type: string brand: description: Brand name. title: Brand type: string description: description: Product description. Empty string when not on file; never null. title: Description type: string image_url: description: >- Absolute HTTPS URL of the product image. Empty string when not on file. title: Image Url type: string category: description: >- Google Product Taxonomy full category path. Empty string when not assigned. title: Category type: string net_content: description: >- Net content with unit (e.g. '500ml', '340g'). Empty string when unknown. title: Net Content type: string country_of_origin: description: >- ISO 3166-1 alpha-2 country code (e.g. 'US', 'IT', 'JP'). Empty string when unknown. title: Country Of Origin type: string certifications: default: [] description: >- Full certification details including validity, issuing body, and verification status. Empty list when no certifications are on file. items: $ref: '#/components/schemas/CertificationDetailOut' title: Certifications type: array claims: default: [] description: >- Product claims with source and validity. Empty list when no claims are on file. items: $ref: '#/components/schemas/ClaimDetailOut' title: Claims type: array substances: default: [] description: >- Substance composition with percentages and allergen flags, ordered by the underlying ``priority`` (declared order on the package). Empty list when no substance data is on file. items: $ref: '#/components/schemas/SubstanceDetailOut' title: Substances type: array required: - gtin - name - brand - description - image_url - category - net_content - country_of_origin title: ProductDetailOut type: object ErrorOut: title: ErrorOut type: object description: RFC 9457 Problem Details error body. properties: type: type: string format: uri title: type: string status: type: integer detail: type: string error_code: type: string retryable: type: boolean timestamp: type: string format: date-time required: - type - title - status - detail examples: - 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' CertificationDetailOut: description: |- Full certification detail with validity and verification status. Mirrors fields from ``CertificationAssignment`` joined with its related ``Certification``. Returned by the product-detail endpoint; see :class:`ClaimDetailOut` for the per-claim variant. examples: - issuing_body: USDA label: USDA Organic valid_from: '2025-01-15' valid_until: '2026-01-15' verification_status: verified properties: label: description: >- Human-readable certification label (e.g. 'USDA Organic', 'Fair Trade Certified'). title: Label type: string issuing_body: default: '' description: >- Name of the organization that issued this certificate (e.g. 'USDA', 'Fair Trade USA'). Empty string when unknown. title: Issuing Body type: string valid_from: anyOf: - type: string - type: 'null' description: ISO 8601 date the certification became valid; null if unknown. title: Valid From valid_until: anyOf: - type: string - type: 'null' description: ISO 8601 date the certification expires; null if it does not expire. title: Valid Until verification_status: allOf: - $ref: '#/components/schemas/CertificationVerificationStatusEnum' default: unverified description: >- How trustworthy this certification record is. ``unverified`` means it was self-declared; ``verified`` means Closient has confirmed it; ``expired`` means a previously-verified certificate has aged out. required: - label title: CertificationDetailOut type: object ClaimDetailOut: description: |- Product claim with source and validity information. Mirrors ``ClaimAssignment`` joined with its related ``Claim``. Note: the ``valid`` boolean is a derived "is currently active" signal — null when validity cannot be determined (e.g. no expiration on file and no explicit validation event). examples: - label: Vegan source: BRAND_SELF_DECLARED valid: true - label: Non-GMO Project Verified source: THIRD_PARTY_VERIFIED valid: true properties: label: description: Human-readable claim label (e.g. 'Vegan', 'Non-GMO', 'Gluten-Free'). title: Label type: string source: allOf: - $ref: '#/components/schemas/ClaimSourceEnum' default: BRAND_SELF_DECLARED description: >- Where the claim originated. ``BRAND_SELF_DECLARED`` is unverified; ``THIRD_PARTY_VERIFIED`` has external corroboration. valid: anyOf: - type: boolean - type: 'null' description: >- Whether the claim is currently active (within its valid_from / expiration_date window). Null when validity cannot be determined. title: Valid required: - label title: ClaimDetailOut type: object SubstanceDetailOut: description: |- Substance composition entry with allergen flag and percentage. Mirrors ``ProductSubstance`` joined with its related ``Substance``. Returned in :class:`ProductDetailOut.substances`, ordered by the underlying ``priority`` (declared order on the package). examples: - is_major_allergen: true may_contain: false name: Almonds percentage: 35 type: FOOD_INGREDIENT - is_major_allergen: false may_contain: false name: Sea Salt percentage: 1.5 type: FOOD_INGREDIENT properties: name: description: Substance name as it appears on the ingredient list. title: Name type: string type: $ref: '#/components/schemas/SubstanceTypeEnum' description: >- Substance category (``FOOD_INGREDIENT``, ``MATERIAL``, ``CHEMICAL``, ``ADDITIVE``, or ``OTHER``). percentage: description: >- Percentage of total product weight this substance contributes (0–100). Values are best-effort; not every product has weighted ingredient data on file. maximum: 100 minimum: 0 title: Percentage type: number is_major_allergen: description: >- True if this substance is one of the major allergens (FDA top-9 / EU 14). title: Is Major Allergen type: boolean may_contain: description: >- True if this is a 'may contain' (cross-contamination) advisory rather than a confirmed ingredient. title: May Contain type: boolean cas_number: anyOf: - type: string - type: 'null' description: >- Chemical Abstracts Service registry number (e.g. '50-00-0' for formaldehyde). Null when unknown. title: Cas Number required: - name - type - percentage - is_major_allergen - may_contain title: SubstanceDetailOut type: object CertificationVerificationStatusEnum: description: |- Mirror of ``CertificationAssignment.VerificationStatus``. Indicates how trustworthy a certification record is. ``unverified`` means it was self-declared and Closient has not validated it; ``verified`` means it has been confirmed against the issuing body; ``expired`` means a previously-verified certificate has aged out. enum: - unverified - verified - expired title: CertificationVerificationStatusEnum type: string ClaimSourceEnum: description: |- Mirror of ``ClaimAssignment.Source``. Where the claim originated. ``BRAND_SELF_DECLARED`` means the brand asserted it without external evidence; ``THIRD_PARTY_VERIFIED`` means a third-party body has confirmed it. enum: - BRAND_SELF_DECLARED - THIRD_PARTY_VERIFIED title: ClaimSourceEnum type: string SubstanceTypeEnum: description: |- Mirror of :class:`apps.substances.models.Substance.SubstanceType`. Identifies the kind of substance a composition entry refers to so an assistant can filter (e.g. show only ``FOOD_INGREDIENT`` for a recipe query, surface ``CHEMICAL`` / ``ADDITIVE`` separately for safety). enum: - FOOD_INGREDIENT - MATERIAL - CHEMICAL - ADDITIVE - OTHER title: SubstanceTypeEnum type: string securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer CookieGatedSessionAuth: type: apiKey in: cookie name: sessionid ````