BackResto Agent API

openapi: 3.2.0
info:
  title: BackResto Public Agent API
  version: 1.0.0
  summary: Free public endpoints of BackResto, the HACCP compliance app for food service professionals.
  description: 'BackResto (https://backresto.com) is a digital HACCP compliance and hygiene tracking app for restaurants, bakeries, caterers, collective catering and hotel kitchens. This specification covers the free, unauthenticated endpoints of the marketing site: the HACCP express audit, the EU allergen table generator, markdown rendering of any page for AI agents, and the health check. The BackResto product app itself (app.backresto.com) has no public API yet. Errors are always structured JSON: `{ "error": string, "code"?: string, "hint"?: string }`. See https://backresto.com/developers for guides and examples.'
  contact:
    name: BackResto
    email: contact@backresto.com
    url: https://www.backresto.com/fr/contact
  termsOfService: https://www.backresto.com/fr/cgu
servers:
- url: https://www.backresto.com
  description: BackResto marketing site
tags:
- name: Agent
  description: Agent-oriented representations of the site
paths:
  /api/markdown/{path}:
    get:
      operationId: getPageAsMarkdown
      tags:
      - Agent
      summary: Render any site page as markdown
      description: 'Returns the markdown representation of the page at the given path (e.g. `fr/tarifs`). Equivalent to requesting the page URL itself with an `Accept: text/markdown` header. Nonexistent pages return HTTP 404 with a markdown recovery body listing where to look next; other errors are structured JSON. The response includes an `x-markdown-tokens` header with an estimated token count.'
      parameters:
      - name: path
        in: path
        required: true
        description: Site path to render, without a leading slash (locale-prefixed, e.g. `fr`, `fr/tarifs`, `en/about`).
        schema:
          type: string
      responses:
        '200':
          description: Markdown representation of the page.
          content:
            text/markdown:
              schema:
                type: string
        '400':
          description: Invalid path (cross-origin or /api/ path).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The page does not exist. The body is a short markdown document with recovery links (sitemap, llms.txt, key pages).
          content:
            text/markdown:
              schema:
                type: string
        '504':
          description: Upstream page render timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      description: Structured error returned by every BackResto endpoint on failure.
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Stable machine-readable error code (e.g. not_found, invalid_path).
        hint:
          type: string
          description: How to resolve the error or where to look next.