Skip to content

AI Context Endpoint Design

Status: Approved Date: 2026-02-02

Overview

Create a /.well-known/ai-context endpoint that returns markdown documentation optimized for LLMs to generate integration code for the middleware.

Requirements

  • Route: GET /.well-known/ai-context
  • Authentication: None (public)
  • Response: text/markdown; charset=utf-8
  • Cache: 1 hour (Cache-Control: public, max-age=3600)

Content Structure

The markdown response includes:

  1. Header - Title and purpose
  2. Overview - What the middleware does, the problem it solves
  3. Architecture - Data flow between Odoo ↔ Middleware ↔ Webshop
  4. Authentication - How Bearer tokens work
  5. Endpoints - All endpoints grouped by direction (inbound/outbound)
  6. Examples - Curl examples with request/response for key flows
  7. Entity Types - List of supported entities

Files to Create

src/Controller/WellKnown/AiContextController.php
src/Service/AiContextGenerator.php
tests/Controller/WellKnown/AiContextControllerTest.php

Implementation Notes

  • Content is dynamically generated (no separate markdown file)
  • Endpoints are hardcoded for better LLM readability (not via OpenAPI reflection)
  • Examples use realistic dummy data based on plan documents
  • Service has separate methods per section for testability

Security

Add /.well-known/ai-context to public access list in security configuration.