{
  "openapi": "3.1.0",
  "info": {
    "title": "Pauhu API",
    "version": "0.2.1",
    "description": "Multilingual knowledge retrieval, terminology, translation, and classification.",
    "contact": {
      "email": "hello@pauhu.ai",
      "url": "https://pauhu.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.pauhu.ai/v1",
      "description": "Production (Helsinki, EU)"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search across knowledge products",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "en"
            }
          },
          {
            "name": "products",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ]
      }
    },
    "/terminology": {
      "get": {
        "summary": "Terminology lookup with sub-microsecond latency",
        "parameters": [
          {
            "name": "term",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "en"
            }
          },
          {
            "name": "target",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ]
      }
    },
    "/translate": {
      "post": {
        "summary": "Retrieval-based translation with provenance",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text",
                  "source_lang",
                  "target_lang"
                ],
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "source_lang": {
                    "type": "string"
                  },
                  "target_lang": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/query": {
      "get": {
        "summary": "Finite text classification",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "en"
            }
          }
        ]
      },
      "post": {
        "summary": "Finite text classification (JSON body)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "lang": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/document/{product}/{id}": {
      "get": {
        "summary": "Fetch document by product and ID",
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP JSON-RPC 2.0 endpoint",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/lds/_catalog": {
      "servers": [
        {
          "url": "https://api.pauhu.eu/v1",
          "description": "Pauhu data products (pauhu.eu)"
        }
      ],
      "get": {
        "summary": "Data-product catalogue: prices and exact counts are live in /v1/lds/_catalog",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "health"
              ]
            }
          }
        ]
      }
    },
    "/lds/draw": {
      "servers": [
        {
          "url": "https://api.pauhu.eu/v1",
          "description": "Pauhu data products (pauhu.eu)"
        }
      ],
      "post": {
        "summary": "Metered draw: without payment a chargeable quote answers HTTP 402 Payment Required with the price and a quote_id; when a prepaid balance can pay it, the 402 carries Link rel=\"payment\" to /v1/lds/balance/topup; repeat with quote_id and Authorization: Bearer <balance token>",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "product_id",
                  "currency"
                ],
                "properties": {
                  "product_id": {
                    "type": "string"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "EUR",
                      "USD"
                    ]
                  },
                  "units": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100
                  },
                  "query": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                  },
                  "quote_id": {
                    "type": "string"
                  },
                  "expected_amount": {
                    "type": "string"
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "units"
                    ]
                  },
                  {
                    "required": [
                      "query",
                      "limit"
                    ]
                  }
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "rows and a receipt, or nothing chargeable"
          },
          "402": {
            "description": "Payment Required: price and quote_id; Link rel=\"payment\" when a prepaid balance can pay"
          },
          "409": {
            "description": "no rail can pay this quote"
          }
        }
      }
    },
    "/lds/balance/topup": {
      "servers": [
        {
          "url": "https://api.pauhu.eu/v1",
          "description": "Pauhu data products (pauhu.eu)"
        }
      ],
      "post": {
        "summary": "Prepaid top-up: answers HTTP 402 with an MPP Challenge; repeat with an MPP Credential carrying a Shared Payment Token; minimum in /v1/lds/_catalog offer",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount",
                  "currency"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "balance token"
          },
          "402": {
            "description": "Payment Required: MPP Challenge"
          }
        }
      }
    },
    "/lds/balance": {
      "servers": [
        {
          "url": "https://api.pauhu.eu/v1",
          "description": "Pauhu data products (pauhu.eu)"
        }
      ],
      "get": {
        "summary": "Prepaid balance of the Authorization: Bearer <balance token>",
        "responses": {
          "200": {
            "description": "balance"
          }
        }
      }
    },
    "/dcat/catalog/{product_id}": {
      "servers": [
        {
          "url": "https://api.pauhu.eu/v1",
          "description": "Pauhu data products (pauhu.eu)"
        }
      ],
      "get": {
        "summary": "Per-product DCAT-AP catalogue (JSON-LD); dcat_url in /v1/lds/_catalog",
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ]
}