API reference

POST /graphql

Reads a listing snapshot by slug.

Request body

type PublixGraphQLRequest = {
  query: string;
  variables?: {
    slug?: string;
  };
};

Pass the slug in variables.slug. Nested fields — menus, categories, products, business, location — are selected inside the listing field.

GET /health

Health probe. Returns 200 when the service is running.

{ "status": "ok" }

Data model

Listing

Root object returned by listing(slug: $slug).

Location

Coordinates (lat, lon) are strings to preserve source precision. Convert with parseFloat only after checking for null.

Business

Menu

Category

Product

Pricing

Prices are strings to preserve decimal precision. Use a decimal library for totals.

ProductMedia

Quantity

Availability

AllergenDisclosure

NutritionValue

Mention

Media

Shared image type used by location.logo, menu.cover, and category.cover.

TypeScript types

export type Media = { url: string | null; alt: string | null } | null;

export type Pricing = {
  price: string;
  currencyCode: string | null;
  unitOfMeasure: string | null;
};

export type Availability = {
  status: "published" | "draft";
  available: boolean;
};

export type AllergenDisclosure = {
  allergenCode: string;
  disclosureType: "contains" | "may_contain";
};

export type NutritionValue = {
  nutrientCode: string;
  amountPerReference: number;
  unit: string;
};

export type Mention = {
  type: "warning" | "regulatory" | "certification" | "custom";
  label: string | null;
  text: string;
};

export type Product = {
  id: string;
  name: string;
  description: string | null;
  pricing: Pricing;
  media: { iconUrl: string | null };
  quantity: {
    displayLabel: string | null;
    netQuantityValue: number | null;
    netQuantityUnit: string | null;
  };
  availability: Availability;
  ingredientsText: string | null;
  allergens: string[];
  allergenDisclosures: AllergenDisclosure[];
  nutritionSummary: string | null;
  nutritionReferenceBasis: "per_100g" | "per_100ml" | null;
  showNutritionPerServing: boolean;
  servingDescription: string | null;
  nutritionValues: NutritionValue[];
  mentions: Mention[];
};

export type Category = {
  id: string;
  name: string;
  description: string | null;
  tags: string[];
  cover: Media;
  products: Product[];
};

export type Menu = {
  id: string;
  name: string;
  description: string | null;
  tags: string[];
  visibility: string;
  cover: Media;
  categories: Category[];
};

export type PublixListing = {
  id: string;
  slug: string;
  visibility: "disabled" | "private" | "public";
  discoveryEnabled: boolean;
  indexingEnabled: boolean;
  createdAt: string;
  updatedAt: string;
  location: {
    displayName: string | null;
    brandColor: string | null;
    city: string | null;
    country: string | null;
    address: string | null;
    lat: string | null;
    lon: string | null;
    currencyCode: string | null;
    locationType: string | null;
    locationCategory: string | null;
    onlineOrdersActive: boolean;
    logo: Media;
  };
  business: {
    displayName: string | null;
    contactEmail: string | null;
    phone: string | null;
    websiteUrl: string | null;
  };
  menus: Menu[];
  products: Product[];
};

Versioning

New fields may be added to any object without a version bump. Existing fields are stable within v1. Code defensively for nullable fields.