{
  "openapi": "3.1.0",
  "info": {
    "title": "DTFOOD Public API",
    "version": "1.0.0",
    "summary": "Machine access to the DTFOOD German-Turkish food marketplace.",
    "description": "Read B2B listings, company profiles, trade fairs and market news, and submit inquiries or quote requests. Authentication is described at https://dtfood.org/auth.md.",
    "contact": {
      "name": "DTFOOD API Support",
      "email": "info@dtfood.org",
      "url": "https://dtfood.org/kontakt"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://dtfood.org/agb"
    }
  },
  "servers": [
    { "url": "https://dtfood.org/api/v1", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Authentication and agent onboarding",
    "url": "https://dtfood.org/auth.md"
  },
  "tags": [
    { "name": "catalog", "description": "Listings, products and companies" },
    { "name": "events", "description": "Trade fairs and delegations" },
    { "name": "content", "description": "News and market intelligence" },
    { "name": "inquiries", "description": "Leads and quote requests" },
    { "name": "metered", "description": "Paid endpoints priced per call" }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "tags": ["catalog"],
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "status": { "type": "string" } } },
                "example": { "status": "ok" }
              }
            }
          }
        }
      }
    },
    "/listings": {
      "get": {
        "operationId": "searchListings",
        "summary": "Search marketplace listings",
        "tags": ["catalog"],
        "security": [{ "oauth2": ["catalog:read"] }, {}],
        "parameters": [
          { "name": "query", "in": "query", "schema": { "type": "string" }, "example": "dried apricots" },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "example": "dried-fruits" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "TR" },
          { "name": "certification", "in": "query", "schema": { "type": "string" }, "example": "halal" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Matching listings",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ListingList" },
                "example": {
                  "items": [
                    {
                      "id": "3f1c",
                      "title": "Organic dried apricots, 12.5 kg cartons",
                      "category": "dried-fruits",
                      "country": "TR",
                      "certifications": ["organic", "halal"],
                      "url": "https://dtfood.org/listings/3f1c"
                    }
                  ],
                  "total": 1
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/listings/{id}": {
      "get": {
        "operationId": "getListing",
        "summary": "Get one listing",
        "tags": ["catalog"],
        "security": [{ "oauth2": ["catalog:read"] }, {}],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "3f1c" }
        ],
        "responses": {
          "200": {
            "description": "Listing detail",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/companies": {
      "get": {
        "operationId": "searchCompanies",
        "summary": "Search the company directory",
        "tags": ["catalog"],
        "security": [{ "oauth2": ["catalog:read"] }, {}],
        "parameters": [
          { "name": "query", "in": "query", "schema": { "type": "string" }, "example": "confectionery" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "DE" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Matching companies",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" } } }
          }
        }
      }
    },
    "/trade-fairs": {
      "get": {
        "operationId": "listTradeFairs",
        "summary": "List food trade fairs and delegations",
        "tags": ["events"],
        "security": [],
        "parameters": [
          { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "TR" },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2027-03-01" }
        ],
        "responses": {
          "200": {
            "description": "Trade fairs",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeFairList" } } }
          }
        }
      }
    },
    "/news": {
      "get": {
        "operationId": "listNews",
        "summary": "List market news and reports",
        "tags": ["content"],
        "security": [],
        "parameters": [
          { "name": "topic", "in": "query", "schema": { "type": "string" }, "example": "export" },
          { "name": "language", "in": "query", "schema": { "type": "string", "enum": ["de", "en", "tr"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "News articles",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsList" } } }
          }
        }
      }
    },
    "/inquiries/halal": {
      "post": {
        "operationId": "createHalalInquiry",
        "summary": "Submit a non-binding halal certification inquiry",
        "tags": ["inquiries"],
        "security": [{ "oauth2": ["leads:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/HalalInquiry" },
              "example": {
                "company": "Anadolu Dairy Ltd.",
                "product_group": "dairy",
                "production_country": "TR",
                "target_markets": ["DE", "FR"],
                "contact_email": "export@example.com",
                "message": "We need halal certification for a new yoghurt line."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Inquiry created",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryResult" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/quotes": {
      "post": {
        "operationId": "createQuoteRequest",
        "summary": "Create a wholesale quote request",
        "tags": ["inquiries"],
        "security": [{ "oauth2": ["orders:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QuoteRequest" },
              "example": {
                "items": [{ "product_id": "p-921", "quantity": 240 }],
                "delivery_country": "DE",
                "contact_email": "buyer@example.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Quote request created",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResult" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/paid/market-report": {
      "get": {
        "operationId": "getPaidMarketReport",
        "summary": "Buy and retrieve one market report",
        "description": "Metered endpoint. Without an `X-PAYMENT` header the endpoint answers HTTP 402 with the full x402 `accepts[]` set.",
        "tags": ["metered", "content"],
        "security": [],
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "mr-2026-08" }
        ],
        "x-payment-info": {
          "protocol": "mpp",
          "version": "1.0",
          "pricing": {
            "type": "per_request",
            "currency": "USDC",
            "amount": "0.50",
            "amount_minor": "500000",
            "decimals": 6
          },
          "settlement": {
            "protocol": "x402",
            "network": "base",
            "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "pay_to": "0x0000000000000000000000000000000000000000",
            "scheme": "exact",
            "discovery": "https://dtfood.org/.well-known/x402.json"
          },
          "payment_methods": ["x402", "card"],
          "free_tier": { "requests": 0 }
        },
        "responses": {
          "200": {
            "description": "Report payload",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketReport" } } }
          },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/paid/supplier-dossier": {
      "get": {
        "operationId": "getPaidSupplierDossier",
        "summary": "Buy and retrieve a verified supplier dossier",
        "tags": ["metered", "catalog"],
        "security": [],
        "parameters": [
          { "name": "company_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "c-4471" }
        ],
        "x-payment-info": {
          "protocol": "mpp",
          "version": "1.0",
          "pricing": {
            "type": "per_request",
            "currency": "USDC",
            "amount": "2.00",
            "amount_minor": "2000000",
            "decimals": 6
          },
          "settlement": {
            "protocol": "x402",
            "network": "base",
            "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "pay_to": "0x0000000000000000000000000000000000000000",
            "scheme": "exact",
            "discovery": "https://dtfood.org/.well-known/x402.json"
          },
          "payment_methods": ["x402", "card"]
        },
        "responses": {
          "200": {
            "description": "Supplier dossier",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }
          },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "See https://dtfood.org/auth.md",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://dtfood.org/oauth/token",
            "scopes": {
              "catalog:read": "Read listings, companies and trade fairs",
              "content:read": "Read news and editorial content"
            }
          },
          "authorizationCode": {
            "authorizationUrl": "https://dtfood.org/oauth/authorize",
            "tokenUrl": "https://dtfood.org/oauth/token",
            "scopes": {
              "leads:write": "Submit inquiries",
              "orders:write": "Create quote requests and bookings"
            }
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid access token",
        "headers": {
          "WWW-Authenticate": {
            "schema": { "type": "string" },
            "example": "Bearer resource_metadata=\"https://dtfood.org/.well-known/oauth-protected-resource\""
          }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": { "Retry-After": { "schema": { "type": "integer" }, "example": 30 } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "PaymentRequired": {
        "description": "Payment required (x402)",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/PaymentRequirements" },
            "example": {
              "x402Version": 1,
              "error": "X-PAYMENT header is required",
              "accepts": [
                {
                  "scheme": "exact",
                  "network": "base",
                  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "maxAmountRequired": "500000",
                  "resource": "https://dtfood.org/api/v1/paid/market-report",
                  "description": "0.50 USDC per market report",
                  "mimeType": "application/json",
                  "payTo": "0x0000000000000000000000000000000000000000",
                  "maxTimeoutSeconds": 60
                }
              ]
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        },
        "required": ["error"]
      },
      "Listing": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "category": { "type": "string" },
          "country": { "type": "string" },
          "certifications": { "type": "array", "items": { "type": "string" } },
          "price": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "updated_at": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "title", "url"]
      },
      "ListingList": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } },
          "total": { "type": "integer" }
        },
        "required": ["items"]
      },
      "Company": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string" },
          "city": { "type": "string" },
          "sectors": { "type": "array", "items": { "type": "string" } },
          "certifications": { "type": "array", "items": { "type": "string" } },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["id", "name"]
      },
      "CompanyList": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } },
          "total": { "type": "integer" }
        },
        "required": ["items"]
      },
      "TradeFair": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string" },
          "city": { "type": "string" },
          "start_date": { "type": "string", "format": "date" },
          "end_date": { "type": "string", "format": "date" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["id", "name", "start_date"]
      },
      "TradeFairList": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/TradeFair" } },
          "total": { "type": "integer" }
        },
        "required": ["items"]
      },
      "NewsArticle": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "language": { "type": "string" },
          "published_at": { "type": "string", "format": "date-time" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["id", "title", "url"]
      },
      "NewsList": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/NewsArticle" } },
          "total": { "type": "integer" }
        },
        "required": ["items"]
      },
      "MarketReport": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "period": { "type": "string" },
          "sections": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": "string" }, "body": { "type": "string" } } } }
        },
        "required": ["id", "title"]
      },
      "HalalInquiry": {
        "type": "object",
        "properties": {
          "company": { "type": "string" },
          "product_group": { "type": "string" },
          "production_country": { "type": "string" },
          "target_markets": { "type": "array", "items": { "type": "string" } },
          "contact_email": { "type": "string", "format": "email" },
          "message": { "type": "string" }
        },
        "required": ["company", "product_group", "contact_email"]
      },
      "InquiryResult": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string", "enum": ["pending"] },
          "received_at": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "status"]
      },
      "QuoteRequest": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "product_id": { "type": "string" },
                "quantity": { "type": "integer" }
              },
              "required": ["product_id", "quantity"]
            }
          },
          "delivery_country": { "type": "string" },
          "contact_email": { "type": "string", "format": "email" }
        },
        "required": ["items", "contact_email"]
      },
      "QuoteResult": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string", "enum": ["pending"] },
          "items_count": { "type": "integer" }
        },
        "required": ["id", "status"]
      },
      "PaymentRequirements": {
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer" },
          "error": { "type": "string" },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string" },
                "network": { "type": "string" },
                "asset": { "type": "string" },
                "maxAmountRequired": { "type": "string" },
                "resource": { "type": "string", "format": "uri" },
                "description": { "type": "string" },
                "mimeType": { "type": "string" },
                "payTo": { "type": "string" },
                "maxTimeoutSeconds": { "type": "integer" }
              },
              "required": ["scheme", "network", "maxAmountRequired", "resource", "payTo"]
            }
          }
        },
        "required": ["x402Version", "accepts"]
      }
    }
  }
}