{
  "openapi": "3.1.0",
  "info": {
    "title": "ByAgents Knowledge API",
    "version": "1.1.0",
    "description": "Public read-only knowledge retrieval. No authentication, live web search, diagnostic execution, vendor ranking, or mutations."
  },
  "servers": [
    {
      "url": "https://byagents.dev"
    }
  ],
  "security": [],
  "paths": {
    "/api/knowledge/search": {
      "get": {
        "operationId": "searchKnowledge",
        "summary": "Search the published ByAgents library",
        "description": "Read-only keyword relevance over this finite library. No live web search or vendor ranking. Unknown or repeated parameters return 400. Results are excerpts; fetch Markdown for the full document. total counts matches before limit.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Trimmed query text. Do not send secrets."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 5
            }
          },
          {
            "name": "audience",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "humans",
                "agents"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "query": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/Document"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "excerpt": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "excerpt"
                            ]
                          }
                        ]
                      }
                    }
                  },
                  "required": [
                    "version",
                    "query",
                    "total",
                    "results"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "const": "invalid_query"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "405": {
            "description": "Unsupported method"
          }
        }
      }
    },
    "/api/knowledge/index": {
      "get": {
        "operationId": "listKnowledge",
        "summary": "List metadata and canonical URLs for all documents",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "updated": {
                      "type": "string",
                      "format": "date"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "documents": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Document"
                      }
                    }
                  },
                  "required": [
                    "version",
                    "updated",
                    "total",
                    "documents"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/content/{audience}/{file}": {
      "get": {
        "operationId": "readKnowledgeMarkdown",
        "summary": "Read a complete document with sources",
        "parameters": [
          {
            "name": "audience",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "humans",
                "agents"
              ]
            }
          },
          {
            "name": "file",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+\\.md$"
            },
            "description": "Slug plus .md. Obtain exact URLs from index or search."
          }
        ],
        "responses": {
          "200": {
            "description": "Complete document",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "Link": {
                "schema": {
                  "type": "string"
                },
                "description": "Canonical HTML representation"
              }
            }
          },
          "404": {
            "description": "Unknown document"
          }
        }
      }
    },
    "/agents/facts.json": {
      "get": {
        "operationId": "getByAgentsFacts",
        "summary": "Read current product capabilities and explicit limits",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": {
                      "type": "string"
                    },
                    "updated": {
                      "type": "string",
                      "format": "date"
                    },
                    "name": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "contact": {
                      "type": "string"
                    },
                    "purpose": {
                      "type": "string"
                    },
                    "website": {
                      "type": "object"
                    },
                    "product_preview": {
                      "type": "object"
                    },
                    "not_available": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "evidence": {
                      "type": "object"
                    },
                    "references": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "schema_version",
                    "updated",
                    "name",
                    "url",
                    "contact",
                    "purpose",
                    "website",
                    "product_preview",
                    "not_available",
                    "evidence",
                    "references"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Document": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "audience": {
            "type": "string",
            "enum": [
              "humans",
              "agents"
            ]
          },
          "category": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "updated": {
            "type": "string",
            "format": "date"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdown_url": {
            "type": "string",
            "format": "uri"
          },
          "level": {
            "type": "string",
            "enum": [
              "Business",
              "Technical",
              "Mixed"
            ],
            "description": "Assumed reader background; not product maturity."
          },
          "outcome": {
            "type": "string",
            "description": "What the document helps a reader produce or decide."
          },
          "published": {
            "type": "string",
            "format": "date",
            "description": "Original publication date, separate from editorial review."
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "audience",
          "category",
          "kind",
          "updated",
          "url",
          "markdown_url"
        ]
      }
    }
  }
}