{ "openapi": "3.1.0", "info": { "title": "Smart 145 Knowledge Base API", "description": "Public HTTP APIs for the Smart 145 knowledge base. Browse and search articles via content negotiation (Accept: text/markdown) or use the chat endpoint for AI-assisted answers grounded in knowledge-base content.", "version": "1.0.0", "contact": { "name": "Smart 145 Support", "email": "sales@smart145.com", "url": "https://knowledgebase.smart145.com/contact" } }, "servers": [ { "url": "https://knowledgebase.smart145.com" } ], "paths": { "/api/v1/chat/send": { "post": { "operationId": "sendChatMessage", "summary": "Send a chat message", "description": "Ask a natural-language question and receive an AI-generated answer grounded in published knowledge-base articles.", "tags": [ "Chat" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 1000, "description": "The user question to answer from knowledge-base content.", "example": "How do I create a repair order?" } } } } } }, "responses": { "200": { "description": "Successful response with an AI-generated answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "description": "Markdown-formatted answer with article citations." }, "processing_time_ms": { "type": "number", "format": "float" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/cache/clear": { "get": { "operationId": "clearCacheGet", "summary": "Clear application cache (GET)", "description": "Flush the application cache. Requires a bearer token or ?token= query parameter matching the configured CACHE_CLEAR_TOKEN.", "tags": [ "Operations" ], "parameters": [ { "name": "token", "in": "query", "required": false, "description": "Cache-clear token (alternative to Authorization header).", "schema": { "type": "string" } } ], "security": [ { "cacheToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/CacheCleared" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "clearCachePost", "summary": "Clear application cache (POST)", "description": "Flush the application cache. Requires a bearer token or ?token= query parameter matching the configured CACHE_CLEAR_TOKEN.", "tags": [ "Operations" ], "parameters": [ { "name": "token", "in": "query", "required": false, "description": "Cache-clear token (alternative to Authorization header).", "schema": { "type": "string" } } ], "security": [ { "cacheToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/CacheCleared" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/": { "get": { "operationId": "listTopics", "summary": "List knowledge-base topics", "description": "Returns the homepage listing all public topics and recent articles. Send Accept: text/markdown to receive markdown instead of HTML.", "tags": [ "Browse" ], "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Set to text/markdown to receive a markdown representation.", "schema": { "type": "string", "example": "text/markdown" } } ], "responses": { "200": { "description": "Topic listing in HTML or markdown.", "content": { "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/{topic}/{slug}": { "get": { "operationId": "getArticle", "summary": "Retrieve a knowledge-base article", "description": "Returns a single published article. Send Accept: text/markdown to receive markdown instead of HTML.", "tags": [ "Browse" ], "parameters": [ { "name": "topic", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Topic slug." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Article slug." }, { "name": "Accept", "in": "header", "required": false, "description": "Set to text/markdown to receive a markdown representation.", "schema": { "type": "string", "example": "text/markdown" } } ], "responses": { "200": { "description": "Article content in HTML or markdown.", "content": { "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/search": { "get": { "operationId": "searchArticles", "summary": "Search knowledge-base articles", "description": "Full-text search over published articles. Returns an HTML results page linking to canonical article URLs.", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query.", "example": "repair order" } ], "responses": { "200": { "description": "HTML search results page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } } }, "components": { "securitySchemes": { "cacheToken": { "type": "http", "scheme": "bearer", "description": "Cache-clear token configured as CACHE_CLEAR_TOKEN on the server." } }, "responses": { "NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found.", "hint": "See /openapi.json for valid endpoints or /.well-known/agent-skills/index.json for agent skills." } } } } }, "ValidationError": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "RateLimited": { "description": "Too many requests.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the Retry-After period.", "hint": "Inspect RateLimit-* response headers and back off until RateLimit-Reset." } } } } }, "Unauthorized": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing token.", "hint": "Provide Authorization: Bearer or ?token=." } } } } }, "Forbidden": { "description": "Action not permitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "CacheCleared": { "description": "Cache cleared successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cache cleared." } } } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "ValidationErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "The given data was invalid." }, "hint": { "type": "string", "example": "Check the errors object for field-level details." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message", "errors" ] } }, "required": [ "error" ] } } }, "tags": [ { "name": "Browse", "description": "Read published knowledge-base content." }, { "name": "Search", "description": "Search published articles." }, { "name": "Chat", "description": "AI-assisted Q&A grounded in knowledge-base articles." }, { "name": "Operations", "description": "Administrative endpoints (token required)." } ], "externalDocs": { "description": "Smart 145 Knowledge Base developer portal", "url": "https://knowledgebase.smart145.com/developers" } }