{
  "openapi": "3.1.0",
  "info": {
    "title": "Paireeo Public Information API",
    "version": "1.0.0",
    "description": "Keyless read-only listing, source search and page lookup. No private data, external URL fetches, bookings or payments. Queries max 500 characters; request bodies max 16 KiB. Hosting may enforce 429 rate limits; honor Retry-After. Version1 keeps this published schema compatible; breaking changes require a new versioned URL and updated specification. Listings use cursor pagination; no asynchronous jobs are used. Send API-Version: 1 (default); responses return API-Version: 1. Deprecation and Sunset headers announce retirement before a supported version is removed. POST /ask is read-only and has no billable or persistent side effects.",
    "contact": {
      "name": "Paireeo Inc.",
      "email": "info@paireeo.com",
      "url": "https://paireeo.info/contact"
    }
  },
  "servers": [
    {
      "url": "https://paireeo.info"
    }
  ],
  "security": [],
  "externalDocs": {
    "url": "https://paireeo.info/docs"
  },
  "paths": {
    "/api/public/pages": {
      "get": {
        "operationId": "readPublicInformation",
        "summary": "List, search, or read published pages",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "description": "Search question about published Paireeo information."
          },
          {
            "name": "path",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Allowlisted public path, e.g. /foundation. Takes precedence over query."
          },
          {
            "name": "API-Version",
            "in": "header",
            "description": "Supported API version. Defaults to 1; unsupported values return 400.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Returned nextCursor; omit to start.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,4}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size for list mode.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page, list of page links, or search results",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "path": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "markdown": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "path",
                        "url",
                        "name",
                        "markdown"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "pages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "path": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Send as cursor to continue; null means complete."
                        },
                        "total": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "pages",
                        "nextCursor",
                        "total"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string",
                                "format": "uri"
                              },
                              "description": {
                                "type": "string"
                              },
                              "score": {
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 100
                              },
                              "grounding": {
                                "type": "object",
                                "properties": {
                                  "sources": {
                                    "type": "array",
                                    "items": {
                                      "type": "string",
                                      "format": "uri"
                                    }
                                  }
                                }
                              }
                            },
                            "required": [
                              "name",
                              "url",
                              "description",
                              "grounding"
                            ]
                          }
                        }
                      },
                      "required": [
                        "results"
                      ]
                    }
                  ]
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Unknown or non-public page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 16 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          }
        },
        "description": "List, search, or read published pages. Results are public source excerpts, not generated advice or a client-specific commitment. All operations are read-only."
      }
    },
    "/ask": {
      "get": {
        "operationId": "searchPublicSources",
        "summary": "NLWeb source search, list mode",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "description": "Search question about published Paireeo information.",
            "required": true
          },
          {
            "name": "streaming",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "API-Version",
            "in": "header",
            "description": "Supported API version. Defaults to 1; unsupported values return 400.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "NLWeb 0.55 answer with cited results, or SSE start/result/complete events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NLWebAnswer"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or JSON",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "type": "object",
                      "required": [
                        "_meta",
                        "error"
                      ],
                      "properties": {
                        "_meta": {
                          "type": "object",
                          "required": [
                            "response_type",
                            "version"
                          ],
                          "properties": {
                            "response_type": {
                              "const": "failure"
                            },
                            "version": {
                              "const": "0.55"
                            }
                          }
                        },
                        "error": {
                          "type": "object",
                          "required": [
                            "code",
                            "message"
                          ],
                          "properties": {
                            "code": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          }
        },
        "description": "NLWeb source search, list mode. Results are public source excerpts, not generated advice or a client-specific commitment. All operations are read-only."
      },
      "post": {
        "operationId": "searchPublicSourcesPost",
        "summary": "NLWeb source search with streaming preference",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "oneOf": [
                      {
                        "type": "object",
                        "required": [
                          "text"
                        ],
                        "properties": {
                          "text": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 500
                          }
                        }
                      },
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      }
                    ],
                    "description": "NLWeb query object. A plain string is also accepted for compatibility."
                  },
                  "prefer": {
                    "type": "object",
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "list"
                        ]
                      },
                      "streaming": {
                        "type": "boolean",
                        "default": false
                      }
                    }
                  }
                }
              },
              "example": {
                "query": {
                  "text": "What does the Foundation Build cost?"
                },
                "prefer": {
                  "mode": "list",
                  "streaming": false
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cited public-source matches",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NLWebAnswer"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or JSON",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "type": "object",
                      "required": [
                        "_meta",
                        "error"
                      ],
                      "properties": {
                        "_meta": {
                          "type": "object",
                          "required": [
                            "response_type",
                            "version"
                          ],
                          "properties": {
                            "response_type": {
                              "const": "failure"
                            },
                            "version": {
                              "const": "0.55"
                            }
                          }
                        },
                        "error": {
                          "type": "object",
                          "required": [
                            "code",
                            "message"
                          ],
                          "properties": {
                            "code": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 16 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Response API version",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              }
            }
          }
        },
        "description": "NLWeb source search with streaming preference. Results are public source excerpts, not generated advice or a client-specific commitment. All operations are read-only.",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "description": "Supported API version. Defaults to 1; unsupported values return 400.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "NLWebAnswer": {
        "type": "object",
        "required": [
          "_meta",
          "results"
        ],
        "properties": {
          "_meta": {
            "type": "object",
            "required": [
              "response_type",
              "version"
            ],
            "properties": {
              "response_type": {
                "const": "answer"
              },
              "version": {
                "const": "0.55"
              }
            }
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "description": {
                  "type": "string"
                },
                "score": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "grounding": {
                  "type": "object",
                  "properties": {
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                }
              },
              "required": [
                "name",
                "url",
                "description",
                "grounding"
              ]
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}