openapi: 3.0.3
info:
  title: "Berger+Team — AI Agents API"
  description: "Das digitale Fundament vom Freelancer Kollektiv Berger+Team: eine schnelle, mehrsprachige Plattform, die dich bei Google und in KI-Antworten sichtbar macht — ohne Cookie-Banner, mit voller Datenhoheit."
  version: "1.0.0"
  contact:
    name: "Berger+Team"
    email: "info@berger.team"
    url: "https://btlabs.dev"
servers:
  - url: "https://btlabs.dev"
    description: Production
paths:
  /api/agents/search:
    get:
      operationId: "search"
      summary: "Volltextsuche über alle indexierten Inhalte. Query-Parameter ?q=<Begriff>"
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
          description: Search term (3+ chars recommended)
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en)."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 10, minimum: 1, maximum: 50 }
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Tool disabled in site settings
  /api/agents/contact:
    get:
      operationId: "contact"
      summary: "Strukturierte Kontaktdaten (E-Mail, Telefon, Adresse, Social)."
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en)."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Tool disabled in site settings
  /api/agents/list/pages:
    get:
      operationId: "list_pages"
      summary: "List published pages (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        slug: { type: string }
                        title: { type: string }
                        url: { type: string, format: uri }
                        mdUrl: { type: string, format: uri }
                        updatedAt: { type: string, format: date-time }
                        description: { type: string }
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/pages/{slug}:
    get:
      operationId: "get_pages"
      summary: "Get a single pages document by slug or numeric id (no auth)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Document slug (or numeric id as fallback)."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/list/posts:
    get:
      operationId: "list_posts"
      summary: "List published posts (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        slug: { type: string }
                        title: { type: string }
                        url: { type: string, format: uri }
                        mdUrl: { type: string, format: uri }
                        updatedAt: { type: string, format: date-time }
                        description: { type: string }
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/posts/{slug}:
    get:
      operationId: "get_posts"
      summary: "Get a single posts document by slug or numeric id (no auth)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Document slug (or numeric id as fallback)."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/list/team:
    get:
      operationId: "list_team"
      summary: "List published team (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      description: "No detail URLs for team — each item embeds the document's public fields (id-based). Relations are reduced to {id, title}."
                      properties:
                        id: { type: integer }
                        title: { type: string }
                        updatedAt: { type: string, format: date-time }
                      additionalProperties: true
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/team/{slug}:
    get:
      operationId: "get_team"
      summary: "Get a single team document by numeric id (no auth — team has no slugs)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Numeric document id (from the list response) — this collection has no slug field."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/list/testimonials:
    get:
      operationId: "list_testimonials"
      summary: "List published testimonials (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      description: "No detail URLs for testimonials — each item embeds the document's public fields (id-based). Relations are reduced to {id, title}."
                      properties:
                        id: { type: integer }
                        title: { type: string }
                        updatedAt: { type: string, format: date-time }
                      additionalProperties: true
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/testimonials/{slug}:
    get:
      operationId: "get_testimonials"
      summary: "Get a single testimonials document by numeric id (no auth — testimonials has no slugs)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Numeric document id (from the list response) — this collection has no slug field."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/list/glossary:
    get:
      operationId: "list_glossary"
      summary: "List published glossary (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        slug: { type: string }
                        title: { type: string }
                        url: { type: string, format: uri }
                        mdUrl: { type: string, format: uri }
                        updatedAt: { type: string, format: date-time }
                        description: { type: string }
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/glossary/{slug}:
    get:
      operationId: "get_glossary"
      summary: "Get a single glossary document by slug or numeric id (no auth)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Document slug (or numeric id as fallback)."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/list/faqs:
    get:
      operationId: "list_faqs"
      summary: "List published faqs (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      description: "No detail URLs for faqs — each item embeds the document's public fields (id-based). Relations are reduced to {id, title}."
                      properties:
                        id: { type: integer }
                        title: { type: string }
                        updatedAt: { type: string, format: date-time }
                      additionalProperties: true
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/faqs/{slug}:
    get:
      operationId: "get_faqs"
      summary: "Get a single faqs document by numeric id (no auth — faqs has no slugs)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Numeric document id (from the list response) — this collection has no slug field."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/list/tags:
    get:
      operationId: "list_tags"
      summary: "List published tags (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        slug: { type: string }
                        title: { type: string }
                        url: { type: string, format: uri }
                        mdUrl: { type: string, format: uri }
                        updatedAt: { type: string, format: date-time }
                        description: { type: string }
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/tags/{slug}:
    get:
      operationId: "get_tags"
      summary: "Get a single tags document by slug or numeric id (no auth)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Document slug (or numeric id as fallback)."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/list/media:
    get:
      operationId: "list_media"
      summary: "List published media (no auth, read-only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection: { type: string }
                  locale: { type: string }
                  count: { type: integer }
                  items:
                    type: array
                    items:
                      type: object
                      description: "No detail URLs for media — each item embeds the document's public fields (id-based). Relations are reduced to {id, title}."
                      properties:
                        id: { type: integer }
                        title: { type: string }
                        updatedAt: { type: string, format: date-time }
                      additionalProperties: true
        '404':
          description: Collection not enabled in site settings
  /api/agents/get/media/{slug}:
    get:
      operationId: "get_media"
      summary: "Get a single media document by numeric id (no auth — media has no slugs)"
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: "Numeric document id (from the list response) — this collection has no slug field."
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (de|it|en). Strict: untranslated fields return null, no fallback."
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale; locale takes precedence."
      responses:
        '200':
          description: Single document (whitelisted public fields)
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Document not found, not published, or noindex
  /api/agents/global/branding:
    get:
      operationId: "global_branding"
      summary: "Read the branding global (no auth, public-safe fields only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (falls back to default for missing translations)"
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale (90-day window); locale takes precedence"
      responses:
        '200':
          description: Public-safe global object
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Global not enabled in site settings
  /api/agents/global/siteSettings:
    get:
      operationId: "global_siteSettings"
      summary: "Read the siteSettings global (no auth, public-safe fields only)"
      parameters:
        - name: locale
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Content locale (falls back to default for missing translations)"
        - name: lang
          in: query
          required: false
          schema: { type: string, default: de }
          description: "Deprecated alias for locale (90-day window); locale takes precedence"
      responses:
        '200':
          description: Public-safe global object
          content:
            application/json:
              schema: { type: object }
        '404':
          description: Global not enabled in site settings