Barcodes.GG Images API

openapi: 3.2.0
info:
  title: Barcodes.gg Images API
  description: Barcodes.gg is a sneaker and streetwear barcode API that resolves UPC and EAN barcodes to products and sizes, and style codes to products and barcodes. Requests are authenticated with a bearer token created in the dashboard and are counted against the monthly allowance of the plan.
  version: 2.0.0
  termsOfService: https://barcodes.gg/legal/terms
  contact:
    name: Barcodes.gg
    email: mail@barcodes.gg
    url: https://barcodes.gg
servers:
- url: https://barcodes.gg/api
  description: Production
security:
- bearerAuth: []
tags:
- name: Images
  description: Product images. No token needed.
paths:
  /image/uid/{product_unique_id}:
    get:
      tags:
      - Images
      operationId: getImageByUid
      summary: Get a product image by unique ID
      description: Returns the image of one exact product variant. No token is needed and the call is not debited. These are the URLs returned in `product_image`. The content type is that of the stored image (WebP, PNG, JPEG, GIF or AVIF).
      security: []
      parameters:
      - name: product_unique_id
        in: path
        required: true
        description: Unique ID of one product variant, as returned in `product_unique_id`. The value may contain slashes.
        schema:
          type: string
        example: DD1391-100_WHITE-BLACK
      - name: resize
        in: query
        required: false
        description: Presence flag. When the parameter is present the image is returned as a 750 by 750 PNG.
        schema:
          type: string
      - name: flip
        in: query
        required: false
        description: Presence flag. With `resize`, mirrors the image horizontally.
        schema:
          type: string
      - name: no_reply
        in: query
        required: false
        description: Presence flag. When no image is available, return an empty `image/png` body with HTTP 200 instead of a JSON error.
        schema:
          type: string
      responses:
        '200':
          description: The image as binary data. When no image is held for the product the response is HTTP 200 with a JSON error body instead.
          content:
            image/*:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: true
                message: Image could not be found.
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/ImageUnavailable'
  /image/{style_code}:
    get:
      tags:
      - Images
      operationId: getImageByStyleCode
      summary: Get a product image by style code
      description: Returns the image stored for a style code. Prefer the unique ID route when several variants share a style code. No token is needed and the call is not debited. These are the URLs returned in `product_image`. The content type is that of the stored image (WebP, PNG, JPEG, GIF or AVIF).
      security: []
      parameters:
      - name: style_code
        in: path
        required: true
        description: Manufacturer style code (SKU). The value may contain slashes. A value starting with `uid/` is routed to the unique ID endpoint.
        schema:
          type: string
        example: DH4756-100
      - name: resize
        in: query
        required: false
        description: Presence flag. When the parameter is present the image is returned as a 750 by 750 PNG.
        schema:
          type: string
      - name: flip
        in: query
        required: false
        description: Presence flag. With `resize`, mirrors the image horizontally.
        schema:
          type: string
      - name: no_reply
        in: query
        required: false
        description: Presence flag. When no image is available, return an empty `image/png` body with HTTP 200 instead of a JSON error.
        schema:
          type: string
      responses:
        '200':
          description: The image as binary data. When no image is held for the product the response is HTTP 200 with a JSON error body instead.
          content:
            image/*:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: true
                message: Image could not be found.
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/ImageUnavailable'
components:
  responses:
    BadRequest:
      description: A parameter failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            validation:
              summary: Validation errors
              value:
                error: true
                message:
                  fields:
                  - The fields field is required.
                response_time: 12ms
                request_fulfilled: false
                request_debited: false
    RateLimited:
      description: The per-minute rate limit of the plan was exceeded. Unauthenticated routes are limited to 30 requests per minute per IP address.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rateLimited:
              summary: Rate limited
              value:
                error: true
                message: Rate limit reached, please wait and try again.
    ImageUnavailable:
      description: The image exists but could not be read from storage.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unavailable:
              summary: Storage error
              value:
                error: true
                message: Image could not be retrieved at this time.
  schemas:
    Error:
      type: object
      description: Error envelope. Lookups that find nothing also use it, with HTTP 200. The three metadata fields are added to v2 JSON responses produced inside the v2 route group; 401 and 429 responses do not carry them.
      required:
      - error
      - message
      properties:
        error:
          type: boolean
          const: true
        message:
          description: A message string, or for validation failures an object mapping each field name to a list of messages.
          oneOf:
          - type: string
          - type: object
            additionalProperties:
              type: array
              items:
                type: string
        response_time:
          type: string
          description: Server runtime of the request, for example `41ms`.
        request_fulfilled:
          type: boolean
          description: True when the HTTP status is below 400.
        request_debited:
          type: boolean
          description: True only when the call was debited from the plan allowance.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API token created in the dashboard under Tokens (Laravel Sanctum personal access token). Send it as `Authorization: Bearer <token>`. Each token carries a set of abilities limited to those of the plan; each endpoint requires one ability. Free Trial tokens expire when the trial ends.'
externalDocs:
  description: Barcodes.gg API documentation
  url: https://barcodes.gg/guide/docs/introduction