openapi: 3.1.1
info:
  title: API pública de Jefe para restaurantes
  version: 1.0.0
  description: API anónima y de sólo lectura para consultar la identidad pública
    de Jefe, guías publicadas y recursos oficiales. No opera pedidos, cuentas ni
    datos de clientes. Los cambios incompatibles usan una nueva versión mayor;
    una operación futura en retiro se documentará y enviará los encabezados HTTP
    Deprecation y Sunset cuando exista una fecha definida.
  contact:
    name: Jefe
    email: felipe@chejefe.com
    url: https://www.chejefe.com/contact
  license:
    name: Términos de uso de la API pública de Jefe
    identifier: LicenseRef-Jefe-Public-API
    url: https://www.chejefe.com/developers
x-api-versioning:
  strategy: major-version-in-path
  current: v1
  policy: https://www.chejefe.com/developers/api-versioning
  deprecation: Breaking changes use a new major path. Deprecated operations are
    documented and use Deprecation and Sunset headers when a retirement date
    exists.
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
servers:
  - url: https://www.chejefe.com
    description: Producción
externalDocs:
  description: Documentación para desarrolladores
  url: https://www.chejefe.com/developers
tags:
  - name: Product
    description: Identidad y capacidades públicas verificables.
  - name: Guides
    description: Catálogo editorial publicado.
  - name: Resources
    description: Recursos oficiales para agentes.
  - name: NLWeb
    description: Búsqueda natural stateless sobre guías públicas.
paths:
  /api/v1/product:
    get:
      tags:
        - Product
      summary: Obtener información pública de Jefe
      description: Devuelve la identidad pública, cobertura, capacidades verificables
        y límites de la superficie de agentes.
      operationId: getJefeProduct
      security: []
      responses:
        "200":
          description: Identidad, cobertura, capacidades, límites y enlaces oficiales.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
              examples:
                product:
                  value:
                    name: Jefe
                    alternateName: Jefe para restaurantes
                    legalName: AticoVentures, LLC
                    description: Plataforma de canal directo para restaurantes.
                    coverage: América Latina hispanohablante.
                    origin: Fundada en Argentina en 2026.
                    capabilities:
                      - Canal directo de pedidos alrededor de WhatsApp
                    limitations:
                      - Esta API es informativa y de sólo lectura.
                    links:
                      website: https://www.chejefe.com
  /api/v1/guides:
    get:
      tags:
        - Guides
      summary: Buscar guías públicas
      description: Busca sólo owners publicados y devuelve paginación mediante un
        cursor opaco.
      operationId: searchJefeGuides
      security: []
      parameters:
        - name: q
          in: query
          description: Texto presente en título, descripción, extracto o categoría.
          schema:
            type: string
            maxLength: 200
        - name: category
          in: query
          description: Nombre exacto de una categoría pública.
          schema:
            type: string
            maxLength: 100
        - name: limit
          in: query
          description: Cantidad de resultados, entre 1 y 50.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: cursor
          in: query
          description: Cursor opaco devuelto por la respuesta anterior.
          schema:
            type: string
            maxLength: 200
      responses:
        "200":
          description: Página estable de guías publicadas.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuideList"
        "400": &a1
          description: La solicitud no se pudo resolver.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /api/v1/guides/{slug}:
    get:
      tags:
        - Guides
      summary: Obtener una guía pública
      description: Recupera metadata canónica y el cuerpo Markdown de una guía
        publicada por su slug exacto.
      operationId: getJefeGuide
      security: []
      parameters:
        - name: slug
          in: path
          required: true
          description: Identificador exacto de una guía publicada.
          schema:
            type: string
            pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
            maxLength: 160
      responses:
        "200":
          description: Metadata canónica y cuerpo Markdown de la guía.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuideDetail"
        "404": *a1
  /api/v1/resources:
    get:
      tags:
        - Resources
      summary: Listar recursos oficiales
      description: Enumera contratos, índices y páginas de confianza públicas de Jefe.
      operationId: listJefeResources
      security: []
      responses:
        "200":
          description: Mapa del sitio, documentación, contratos y páginas de confianza.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceList"
  /ask:
    get:
      tags:
        - NLWeb
      summary: Consultar guías públicas mediante NLWeb
      description: "Acepta una pregunta en lenguaje natural, busca owners publicados y
        devuelve resultados Schema.org. streaming=true o Accept:
        text/event-stream habilita SSE."
      operationId: askJefeGuides
      security: []
      parameters:
        - name: query
          in: query
          required: true
          description: Pregunta o tarea del restaurante.
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - name: streaming
          in: query
          description: Devuelve eventos start, result y complete mediante SSE.
          schema:
            type: boolean
            default: false
        - name: mode
          in: query
          description: La superficie pública admite únicamente búsqueda list.
          schema:
            type: string
            const: list
            default: list
      responses:
        "200":
          description: Respuesta NLWeb 0.55 o stream SSE equivalente.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NlWebResponse"
            text/event-stream:
              schema:
                type: string
        "400": *a1
    post:
      tags:
        - NLWeb
      summary: Consultar NLWeb con un cuerpo estructurado
      description: Admite el cuerpo NLWeb 0.55 con query.text y prefer.streaming. Sólo
        consulta el catálogo público y no llama a un modelo generativo.
      operationId: askJefeGuidesStructured
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NlWebRequest"
      responses:
        "200":
          description: Respuesta NLWeb 0.55 o stream SSE equivalente.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NlWebResponse"
            text/event-stream:
              schema:
                type: string
        "400": *a1
        "413": *a1
components:
  securitySchemes: {}
  schemas:
    Product:
      type: object
      additionalProperties: false
      required:
        - name
        - alternateName
        - legalName
        - description
        - coverage
        - origin
        - capabilities
        - limitations
        - links
      properties:
        name:
          type: string
          const: Jefe
        alternateName:
          type: string
          const: Jefe para restaurantes
        legalName:
          type: string
          const: AticoVentures, LLC
        description:
          type: string
        coverage:
          type: string
        origin:
          type: string
        capabilities:
          type: array
          items:
            type: string
        limitations:
          type: array
          items:
            type: string
        links:
          type: object
          additionalProperties:
            type: string
            format: uri
    GuideSummary:
      type: object
      additionalProperties: false
      required:
        - slug
        - title
        - description
        - excerpt
        - category
        - canonical
        - publishedAt
        - author
        - readingTime
      properties:
        slug:
          type: string
        title:
          type: string
        description:
          type: string
        excerpt:
          type: string
        category:
          type: string
        canonical:
          type: string
          format: uri
        publishedAt:
          type: string
        updatedAt:
          type: string
        author:
          type: string
        readingTime:
          type: string
    GuideDetail:
      allOf:
        - $ref: "#/components/schemas/GuideSummary"
        - type: object
          required:
            - markdown
          properties:
            markdown:
              type: string
    GuideList:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
        - total
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/GuideSummary"
        nextCursor:
          type:
            - string
            - "null"
        total:
          type: integer
          minimum: 0
    Resource:
      type: object
      additionalProperties: false
      required:
        - name
        - description
        - url
        - mediaType
      properties:
        name:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        mediaType:
          type: string
    ResourceList:
      type: object
      additionalProperties: false
      required:
        - resources
      properties:
        resources:
          type: array
          items:
            $ref: "#/components/schemas/Resource"
    NlWebRequest:
      type: object
      additionalProperties: false
      required:
        - query
      properties:
        query:
          oneOf:
            - type: string
              minLength: 1
              maxLength: 200
            - type: object
              additionalProperties: false
              required:
                - text
              properties:
                text:
                  type: string
                  minLength: 1
                  maxLength: 200
        mode:
          type: string
          const: list
        streaming:
          type: boolean
        prefer:
          type: object
          additionalProperties: false
          properties:
            mode:
              type: string
              const: list
            streaming:
              type: boolean
        meta:
          type: object
          additionalProperties: true
    NlWebResult:
      type: object
      additionalProperties: false
      required:
        - url
        - name
        - site
        - score
        - description
        - schema_object
      properties:
        url:
          type: string
          format: uri
        name:
          type: string
        site:
          type: string
          const: chejefe.com
        score:
          type: number
          minimum: 0
        description:
          type: string
        schema_object:
          type: object
          additionalProperties: true
    NlWebResponse:
      type: object
      additionalProperties: false
      required:
        - _meta
        - query_id
        - query
        - results
      properties:
        _meta:
          type: object
          additionalProperties: false
          required:
            - version
            - response_type
            - mode
            - site
          properties:
            version:
              type: string
              const: "0.55"
            response_type:
              type: string
              const: answer
            mode:
              type: string
              const: list
            site:
              type: string
              const: chejefe.com
        query_id:
          type: string
          format: uuid
        query:
          type: string
        results:
          type: array
          items:
            $ref: "#/components/schemas/NlWebResult"
    Problem:
      type: object
      additionalProperties: false
      required:
        - type
        - status
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          format: uri
        status:
          type: integer
          minimum: 400
          maximum: 599
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
