openapi: 3.1.0
info:
  title: Lokal Local Food Agent API
  description: Discover local food producers across Norway. 400+ farms, markets, and shops.
  version: 0.11.0
servers:
  - url: https://lokal.fly.dev
    description: Production
paths:
  /api/marketplace/search:
    get:
      operationId: searchFood
      summary: Natural language food search
      description: Search for local food using natural language in Norwegian or English.
      parameters:
        - name: q
          in: query
          required: true
          description: Natural language search query
          schema:
            type: string
          example: "ost nær Bergen"
        - name: limit
          in: query
          required: false
          description: Max results (default 20)
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  query:
                    type: string
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        relevanceScore:
                          type: number
                        distanceKm:
                          type: number
                        matchReasons:
                          type: array
                          items:
                            type: string
                        agent:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            description:
                              type: string
                            categories:
                              type: array
                              items:
                                type: string
                            tags:
                              type: array
                              items:
                                type: string
                            location:
                              type: object
                              properties:
                                city:
                                  type: string
                                lat:
                                  type: number
                                lng:
                                  type: number
  /api/marketplace/discover:
    post:
      operationId: discoverProducers
      summary: Structured producer discovery
      description: Find producers by category, tags, and location.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                categories:
                  type: array
                  items:
                    type: string
                tags:
                  type: array
                  items:
                    type: string
                lat:
                  type: number
                  description: Latitude (e.g. 59.91 for Oslo)
                lng:
                  type: number
                  description: Longitude (e.g. 10.75 for Oslo)
                maxDistanceKm:
                  type: number
                  default: 50
                limit:
                  type: integer
                  default: 20
      responses:
        "200":
          description: Matched producers
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        relevanceScore:
                          type: number
                        distanceKm:
                          type: number
                        agent:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            description:
                              type: string
                            categories:
                              type: array
                              items:
                                type: string
                            location:
                              type: object
                              properties:
                                city:
                                  type: string
                                lat:
                                  type: number
                                lng:
                                  type: number
  /api/marketplace/agents/{agentId}/info:
    get:
      operationId: getProducerInfo
      summary: Get producer details
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Producer details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      agent:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          description:
                            type: string
                      knowledge:
                        type: object
                        properties:
                          address:
                            type: string
                          products:
                            type: array
                            items:
                              type: string
                          openingHours:
                            type: string
  /api/stats:
    get:
      operationId: getPlatformStats
      summary: Platform statistics
      responses:
        "200":
          description: Stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      totalAgents:
                        type: integer
                      totalCities:
                        type: integer
                      totalInteractions:
                        type: integer