# What the LabelSage iPhone app asks the LabelSage server for. Public summary for reviewers and users.
# Only the calls the app makes are listed. Checked against https://api.labelsage.app on 2026-11-19.
openapi: 3.1.0
info:
  title: LabelSage app API (public summary)
  version: "2026-11-19"
  description: >-
    The read-only calls the LabelSage iPhone app makes to look up products and load product photos.
    There is no account and no sign-in. Every request carries the same two headers for everyone
    (User-Agent: LabelSage, Accept-Language: en) and no cookie, device identifier or advertising
    identifier. A request carries only a barcode, search words or a product category. Names, household
    members, allergies and diets stay on the iPhone, and the check against them happens on the iPhone.
    Errors are JSON in the form {"error": "code"}. Too many requests from one address get 429.
    Human summary: https://labelsage.app/data
servers:
  - url: https://api.labelsage.app
tags:
  - name: config
    description: Feature switches read at launch
  - name: products
    description: Product lookup by barcode and search by words or category
  - name: images
    description: Product photos
paths:
  /v1/config.json:
    get:
      tags: [config]
      summary: Feature switches
      operationId: getConfig
      description: >-
        Read at launch, at most once an hour. The request carries nothing. A switch can only turn a
        feature off. On 2026-11-19 the file was not published and the server answered 404; the app then
        keeps its built-in settings.
      responses:
        "200":
          description: The switches. Keys the app does not know are ignored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Config"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/products/{code}:
    get:
      tags: [products]
      summary: One product by barcode
      operationId: getProduct
      description: Sent when a barcode is scanned or a product is opened. Carries the barcode.
      parameters:
        - name: code
          in: path
          required: true
          description: "8 to 14 digits: EAN-8, UPC-A, EAN-13 or GTIN-14"
          schema:
            type: string
            pattern: "^[0-9]{8,14}$"
          example: "051500241288"
      responses:
        "200":
          description: The product with its ingredients, allergens and nutrients.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/products:
    get:
      tags: [products]
      summary: Search products by name, brand or category
      operationId: searchProducts
      description: >-
        Sent for a name search, and to find other options in the same category as a product. Carries the
        search words or the product's category.
      parameters:
        - name: q
          in: query
          required: true
          description: Search words, or a product category
          schema:
            type: string
            minLength: 2
            maxLength: 80
          example: milk
        - name: limit
          in: query
          required: false
          description: Most results to return
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          example: 20
        - name: full
          in: query
          required: false
          description: >-
            When true, each result includes its ingredient list, so the app does not send one lookup per
            result. Carries no user data. If the server answers 422, the app looks up each result by
            barcode instead. On 2026-11-19 the server answered 422 for this parameter.
          schema:
            type: boolean
            default: false
          example: true
      responses:
        "200":
          description: Matching products in short form.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/images/{gtin14}/{name}:
    get:
      tags: [images]
      summary: A product photo
      operationId: getProductImage
      description: >-
        The app takes this address from the product's image field. Carries the photo's address, which
        includes the barcode. The app loads photos only from this server, over https, and refuses any
        other host. Many of the photos come from Open Food Facts.
      parameters:
        - name: gtin14
          in: path
          required: true
          description: The barcode as 14 digits
          schema:
            type: string
            pattern: "^[0-9]{14}$"
          example: "00051500241288"
        - name: name
          in: path
          required: true
          description: "thumb.webp (200 px long side) or detail.webp (800 px long side)"
          schema:
            type: string
            enum: [thumb.webp, detail.webp]
        - name: v
          in: query
          required: false
          description: Version of the photo, copied from the product's image address
          schema:
            type: string
            maxLength: 64
      responses:
        "200":
          description: The photo as WebP.
          content:
            image/webp:
              schema:
                type: string
                format: binary
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
components:
  responses:
    BadRequest:
      description: "invalid_barcode: the barcode is not 8 to 14 digits"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example: {error: invalid_barcode}
    NotFound:
      description: "not_found: no such product or photo"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example: {error: not_found}
    InvalidRequest:
      description: "invalid_request: an unknown parameter or a value out of range"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example: {error: invalid_request}
    TooManyRequests:
      description: Too many requests from one address. Try again after the Retry-After seconds.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          example: not_found
    Config:
      type: object
      description: Each switch is a JSON true or false. Only false changes anything.
      properties:
        live_products:
          type: boolean
          description: false turns off looking up products on the server
        product_photos:
          type: boolean
          description: false turns off loading product photos
      example: {live_products: true, product_photos: true}
    Image:
      type: [object, "null"]
      properties:
        thumb:
          $ref: "#/components/schemas/ImageFile"
        detail:
          $ref: "#/components/schemas/ImageFile"
        credit:
          type: string
        license:
          type: string
    ImageFile:
      type: object
      required: [url, width, height]
      properties:
        url:
          type: string
          description: A /v1/images/... path on this server
          example: /v1/images/00012345678905/thumb.webp?v=3f9a0c1d2e4b
        width:
          type: integer
        height:
          type: integer
    ProductSummary:
      type: object
      required: [gtin14, name]
      properties:
        gtin14:
          type: string
          example: "00051500241288"
        name:
          type: string
          example: Creamy Peanut Butter
        brand:
          type: [string, "null"]
          example: Jif
        category:
          type: [string, "null"]
          example: Nut & Seed Butters
        size:
          type: [string, "null"]
          example: 16 oz (1 lb) 454 g
        image:
          $ref: "#/components/schemas/Image"
        recalls:
          type: array
          items:
            type: object
        discontinued:
          type: boolean
        sources:
          type: array
          items:
            type: string
          example: [fdc, off]
        attribution:
          type: array
          items:
            type: string
        updated_at:
          type: string
          example: "2025-02-04"
        catalog_version:
          type: string
          example: v2026-45
    Product:
      allOf:
        - $ref: "#/components/schemas/ProductSummary"
        - type: object
          properties:
            ingredients:
              type: [object, "null"]
              description: The ingredient list as printed on the label
              properties:
                raw_text:
                  type: [string, "null"]
            allergens:
              type: [object, "null"]
              description: Allergens the label says the product contains or may contain
              properties:
                contains_tags:
                  type: array
                  items:
                    type: string
                  example: ["en:peanuts", "en:soybeans"]
                may_contain_tags:
                  type: array
                  items:
                    type: string
            nutrients:
              type: [object, "null"]
              description: Nutrients per 100 g or 100 ml
            serving:
              type: [object, "null"]
            processing:
              type: [object, "null"]
    SearchResponse:
      type: object
      required: [products]
      properties:
        catalog_version:
          type: string
          example: v2026-45
        products:
          type: array
          items:
            $ref: "#/components/schemas/ProductSummary"
